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

# API Paths

> Choose between app-scoped API Trigger keys and Developer Platform Account API keys.

## Two supported paths

CREAO supports two API paths for running agents:

| Path                   | Key prefix | Base URL                                     | Request identity         | Input field |
| ---------------------- | ---------- | -------------------------------------------- | ------------------------ | ----------- |
| App-scoped API Trigger | `capi_`    | `https://agent.creao.ai/api/v1/apps/{appId}` | `appId` in the URL       | `inputs`    |
| Developer Platform API | `cr_sk_`   | `https://developer.creao.ai/v1`              | Account-owned `agent_id` | `input`     |

Both are current supported paths. They serve different product entry points and keep separate key scopes, route families, and request shapes.

## App-scoped API Trigger

Use this path when you want a key that can only run one specific agent. Create the key from the agent detail page in `agent.creao.ai`.

```bash theme={null}
curl -X POST "https://agent.creao.ai/api/v1/apps/00000000-0000-4000-8000-000000000000/runs" \
  -H "Authorization: Bearer capi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": { "topic": "weekly report" }
  }'
```

## Developer Platform API

Use this path when your backend needs account-level agent lifecycle management, async run records, realtime SSE, webhooks, or usage analytics. Create the key in [Developer Console](https://developer.creao.ai/).

```bash theme={null}
curl -X POST https://developer.creao.ai/v1/runs \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-000000000000",
    "input": { "ticker": "AAPL", "reporting_period": "2025 Q4" }
  }'
```

## Contract comparison

| Concern            | App-scoped API Trigger                  | Developer Platform API                                                  |
| ------------------ | --------------------------------------- | ----------------------------------------------------------------------- |
| Key creation       | Agent detail page in `agent.creao.ai`   | Developer Console                                                       |
| Key scope          | One agent                               | Account-owned personal agents                                           |
| Key prefix         | `capi_`                                 | `cr_sk_`                                                                |
| Agent create route | Not supported                           | `POST /v1/agents`                                                       |
| Agent update route | Not supported                           | `PATCH /v1/agents/{agent_id}` replaces provided fields                  |
| Agent edit route   | Not supported                           | `POST /v1/agents/{agent_id}/edits` starts a natural-language edit       |
| Agent edit status  | Not supported                           | `GET /v1/agents/{agent_id}/edits/{run_id}`                              |
| Async create route | `POST /api/v1/apps/{appId}/runs`        | `POST /v1/runs`                                                         |
| Status route       | `GET /api/v1/apps/{appId}/runs/{runId}` | `GET /v1/runs/{run_id}`                                                 |
| List route         | `GET /api/v1/apps/{appId}/runs`         | `GET /v1/runs`                                                          |
| Realtime SSE       | Not exposed on this path                | `POST /v1/realtime/runs`                                                |
| Webhooks           | Supported by app-run request body       | Supported by `webhook_url`                                              |
| Conversation reuse | App-run/thread semantics                | `conversation_id`                                                       |
| Request body       | `inputs`, plus app-run options          | `agent_id`, `input`, optional `conversation_id`, optional `webhook_url` |

## Keep route families separate

Do not send Developer Platform request bodies to `agent.creao.ai/api/v1/*`, and do not send app-scoped request bodies to `developer.creao.ai/v1/*`.

For example, `/v1/runs` expects `agent_id` and `input`, not `appId` or `inputs`. The app-scoped path already has the agent id in the URL and expects `inputs`.