Skip to main content
The Platform API is a REST API for managing prompts, running them on AI models (ChatGPT, Perplexity, and others), and collecting and analyzing the answers. For the full endpoint schema, see the API Reference.
If you want to use Chainshift without writing code, see the usage guide instead of this document. That approach sends natural-language requests through an AI tool. Use the REST API when you need programmatic access, such as custom aggregation or dashboard integration.

Base URL

The path requires the /api prefix. If you call the path shown in the API Reference (/v1/platform/…) without /api, the API returns a SYSTEM_BAD_REQUEST error.

Authentication

Pass your organization API key in the API-Key header. Every request is scoped to the organization that owns the key. See API key for details.

Resource structure

See Core concepts for how resources relate to each other.
Brands are independent of the collection pipeline. A run request does not require a brand. Analysis that finds brand mentions in answers works by matching the brand name and synonyms against the answer body (content) and sources (sources).

Common rules

Pagination

List endpoints return nextCursor in the response. Pass that value as the cursor query parameter in the next request to get the next page. null means the last page. Set the page size with limit (default 20, max 100, except GET /runs, which allows up to 10). See Retrieving answers for details.

ID format

Every resource ID is a 22-character string (for example, GULjgaLy-DjX9NAVxjZBFg). A malformed ID is rejected with 400, not 404.

Date format

Dates and times are RFC3339 strings (for example, 2026-07-28T09:41:00Z).

Error format

An error response consists of code, message, and an optional details.
An invalid API key returns 401, insufficient credits returns 402 (INSUFFICIENT_CREDITS), and exceeding the rate limit returns 429 (PLATFORM_RATE_LIMIT_EXCEEDED). See Error handling for the full list of codes and the retry strategy.

Basic flow

This is the call sequence for programmatic use.
1

Prepare prompts

Create a set with POST /prompt-sets and register questions with POST /prompts (or /prompts/bulk).
2

Submit a run

Send prompts (promptIDs or promptSetID) and models (models) to POST /runs. The response returns a runID.
3

Poll for completion

Poll GET /runs/{runID} about every 30 seconds until status becomes FINISHED. Collection usually takes a few minutes.
4

Retrieve answers

Call GET /answers?runID={runID} to get the answer body (content), sources (sources), and fan-out queries (fanouts). Narrow the analysis scope with the promptSetID, model, and from/to filters.
See Running prompts for a detailed walkthrough of each step.