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

# 개요

> Platform REST API의 베이스 URL, 인증, 리소스 구조와 공통 규칙

Platform API는 프롬프트를 관리하고, AI 모델(ChatGPT, Perplexity 등)에 프롬프트를 실행해 답변을 수집·분석하는 REST API입니다. 전체 엔드포인트 스키마는 [API Reference](https://dev-platform-api.trychainshift.ai/swagger/doc.json)를 참고하세요.

<Note>
  코드 없이 사용하려면 이 문서 대신 [활용 가이드](/usage)를 보세요. AI 도구에 자연어로 요청하는 방식이며, REST API는 직접 집계나 대시보드 연동 등 프로그래밍 방식이 필요할 때 사용합니다.
</Note>

## 베이스 URL

```
https://dev-platform-api.trychainshift.ai/api/v1beta/platform
```

<Warning>
  경로에 `/api` 접두사가 필요합니다. API Reference의 경로(`/v1beta/platform/…`)만 보고 `/api` 없이 호출하면 `SYSTEM_BAD_REQUEST` 에러가 반환됩니다.
</Warning>

## 인증

조직 API 키를 `API-Key` 헤더로 전달합니다. 모든 요청은 키가 속한 조직으로 범위가 한정됩니다. 자세한 내용은 [API 키](/authentication/api-key)를 참고하세요.

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

## 리소스 구조

| 리소스                     | 역할                                      |
| ----------------------- | --------------------------------------- |
| 프롬프트 세트 (`prompt-sets`) | 관련 프롬프트를 묶는 단위                          |
| 프롬프트 (`prompts`)        | AI 모델에 실행할 질문. 반드시 하나의 세트에 속합니다         |
| 프롬프트 실행 (`runs`)        | 프롬프트 × 모델 조합의 실행 단위. 제출하면 수집이 시작됩니다     |
| 답변 (`answers`)          | 실행 결과. 본문, 인용 출처, 검색 쿼리(fan-out)를 포함합니다 |
| 통계 (`…/statistics`)     | 답변을 서버에서 집계한 랭킹 (도메인·URL·토큰·fan-out)    |
| 브랜드 (`brands`)          | 분석 기준이 되는 브랜드 정보(이름·동의어·웹사이트)           |
| 키워드 (`keywords`)        | 구글·네이버 검색 데이터                           |

리소스 간 관계는 [핵심 개념](/concepts)을 참고하세요.

<Note>
  브랜드는 수집 파이프라인과 독립된 리소스입니다. 실행 요청에 브랜드가 필요하지 않으며, 답변에서 브랜드 언급을 찾는 분석은 브랜드의 이름·동의어를 답변 본문(`content`)·출처(`sources`)와 대조하는 방식으로 수행합니다.
</Note>

## 공통 규칙

### 페이지네이션

목록 엔드포인트는 응답에 `nextCursor`를 반환합니다. 이 값을 다음 요청의 `cursor` 쿼리 파라미터로 전달하면 다음 페이지를 가져오고, `null`이면 마지막 페이지입니다. 페이지 크기는 `limit`으로 지정합니다(기본 20, 최대 100 — 단, `GET /runs`는 최대 10). 자세한 규칙은 [답변 수집하기](/guides/collecting-answers#페이지네이션)를 참고하세요.

### ID 형식

모든 리소스 ID는 22자 문자열입니다(예: `GULjgaLy-DjX9NAVxjZBFg`). 형식이 잘못된 ID는 `404`가 아니라 `400`으로 거부됩니다.

### 날짜 형식

날짜·시간은 RFC3339 문자열입니다(예: `2026-07-28T09:41:00Z`).

### 에러 형식

에러 응답은 `code`, `message`와 선택적 `details`로 구성됩니다.

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

잘못된 API 키는 `401`, 크레딧 부족은 `402`(`INSUFFICIENT_CREDITS`), 요청 한도 초과는 `429`(`PLATFORM_RATE_LIMIT_EXCEEDED`)를 반환합니다. 전체 코드 목록과 재시도 전략은 [에러 처리](/guides/error-handling)를 참고하세요.

## 기본 흐름

프로그래밍 방식으로 사용할 때의 호출 순서입니다.

<Steps>
  <Step title="프롬프트 준비">
    `POST /prompt-sets`로 세트를 만들고 `POST /prompts`(또는 `/prompts/bulk`)로 질문을 등록합니다.
  </Step>

  <Step title="수집 실행">
    `POST /runs`에 프롬프트(`promptIDs` 또는 `promptSetID`)와 모델(`models`)을 전달하면 `runID`가 반환됩니다.
  </Step>

  <Step title="완료 폴링">
    `GET /runs/{runID}`의 `status`가 `FINISHED`가 될 때까지 30초 정도 간격으로 조회합니다. 수집은 보통 수 분 걸립니다.
  </Step>

  <Step title="답변 조회">
    `GET /answers?runID={runID}`로 답변 본문(`content`), 인용 출처(`sources`), 검색 쿼리(`fanouts`)를 가져옵니다. `promptSetID`·`model`·`from`/`to` 필터로 분석 범위를 좁힐 수 있습니다.
  </Step>
</Steps>

단계별 상세 설명은 [프롬프트 실행하기](/guides/submitting-runs)를 참고하세요.