> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychainshift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Base URL, authentication, resource structure, and common rules of the Platform REST API

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](https://platform-api.trychainshift.ai/swagger/doc.json).

> [!NOTE]
>
> If you want to use Chainshift without writing code, see the [usage guide](https://docs.trychainshift.ai/en/mcp/guide.md)
> 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

```
https://platform-api.trychainshift.ai/api/v1/platform
```

> [!WARNING]
>
> 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](https://docs.trychainshift.ai/en/authentication/api-key.md) for details.

```bash theme={null}
curl -H "API-Key: cs_live_xxxxxxxx" \
  "https://platform-api.trychainshift.ai/api/v1/platform/models"
```

## Resource structure

| Resource | Role |
| - | - |
| Prompt sets (`prompt-sets`) | Group related prompts |
| Prompts (`prompts`) | Questions to run on AI models. Every prompt belongs to exactly one set |
| Runs (`runs`) | A unit of execution for prompt × model combinations. Submitting one starts collection |
| Answers (`answers`) | Run results. Include the body, sources, and fan-out queries |
| Statistics (`…/statistics`) | Server-side rankings aggregated from answers (domains, URLs, fan-out) |
| Brands (`brands`) | Brand information used as the basis for analysis (name, synonyms, website) |
| Keywords (`keywords`) | Google and Naver search data |

See [Core concepts](https://docs.trychainshift.ai/en/concepts.md) for how resources relate to each other.

> [!NOTE]
>
> 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](https://docs.trychainshift.ai/en/guides/collecting-answers.md#pagination) 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`.

```json theme={null}
{
  "code": "PROMPT_SET_NOT_FOUND",
  "message": "프롬프트 세트를 찾을 수 없습니다"
}
```

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](https://docs.trychainshift.ai/en/guides/error-handling.md) 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](https://docs.trychainshift.ai/en/guides/submitting-runs.md) for a detailed walkthrough of each step.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.