> ## 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 Trigger

> Run CREAO agents programmatically through app-scoped API keys or Developer Platform Account API keys.

## Overview

CREAO supports two API paths for running agents programmatically:

| Path                   | Create the key in                         | Key prefix | Endpoint family                                   | Best for                                                                                          |
| ---------------------- | ----------------------------------------- | ---------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| App-scoped API Trigger | The agent detail page in `agent.creao.ai` | `capi_`    | `https://agent.creao.ai/api/v1/apps/{appId}/runs` | Calling one specific agent from a script or backend                                               |
| Developer Platform API | Developer Console at `developer.creao.ai` | `cr_sk_`   | `https://developer.creao.ai/v1/*`                 | Account-level backend integrations, async runs, realtime streaming, webhooks, and usage analytics |

Both paths run CREAO agents you own and consume credits from your CREAO account balance. Developer Platform can also create personal agents, update agents by replacing provided fields, and request natural-language edits. They are current supported paths with different key scopes, route families, and request shapes.

<Tip>
  For the Developer Platform endpoint reference, see the [API Reference](/api-reference/overview). For a side-by-side contract summary, see [API Paths](/api-reference/api-paths).
</Tip>

<Warning>
  API keys are server-side secrets. Do not put `capi_` or `cr_sk_` keys in browser frontend code, mobile apps, public repositories, client logs, or analytics events.
</Warning>

## Which path should I use?

Use the app-scoped API Trigger when you want a key that can run only one agent. This is the path shown from the agent page in `agent.creao.ai`, and it uses `inputs` in the request body.

Use Developer Platform when your backend owns an account-level integration. Developer Platform keys can create, edit, and run personal agents owned by the same account, use `agent_id` and `input`, and support async polling, realtime SSE, webhooks, and account-level analytics.

## App-scoped API Trigger

Create an app-scoped API key from the agent detail page in `agent.creao.ai`. The key starts with `capi_` and is scoped to that agent.

### Create a run

```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": {
      "company": "Apple",
      "year": "2025"
    }
  }'
```

The response is accepted for background execution:

```json theme={null}
{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "appId": "00000000-0000-4000-8000-000000000000",
  "appName": "Research Agent"
}
```

### Poll a run

```bash theme={null}
curl "https://agent.creao.ai/api/v1/apps/00000000-0000-4000-8000-000000000000/runs/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer capi_your_key_here"
```

Poll until `status` becomes `completed`, `failed`, or `cancelled`.

## Developer Platform API

Create an Account API key in [Developer Console](https://developer.creao.ai/). Developer Platform keys start with `cr_sk_` and are sent as Bearer tokens to `developer.creao.ai/v1/*`.

<Steps>
  <Step title="Create an Account API key">
    Open [Developer Console](https://developer.creao.ai/), go to **API Keys**, and create a key. Store the full key immediately because it is shown only once.
  </Step>

  <Step title="Find the agent ID">
    Start a personal-agent creation run through `POST /v1/agents` and poll it for the new `agent_id`, or open **Agents** in Developer Console and copy the `agent_id` for an existing agent. Browser-based editing, files, schedules, and debugging still live in `agent.creao.ai`.
  </Step>

  <Step title="Create an async run">
    ```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": {
          "company": "Apple",
          "year": "2025"
        }
      }'
    ```

    The API returns `202 Accepted` with a run ID and conversation ID:

    ```json theme={null}
    {
      "run_id": "11111111-1111-4111-8111-111111111111",
      "status": "pending",
      "agent_id": "00000000-0000-4000-8000-000000000000",
      "conversation_id": "22222222-2222-4222-8222-222222222222"
    }
    ```
  </Step>

  <Step title="Poll for the result">
    ```bash theme={null}
    curl https://developer.creao.ai/v1/runs/11111111-1111-4111-8111-111111111111 \
      -H "Authorization: Bearer cr_sk_your_key_here"
    ```

    Poll until `status` becomes `completed`, `failed`, or `cancelled`.
  </Step>
</Steps>

## Developer Platform reference

### Create an agent

```
POST /v1/agents
```

#### JSON body

| Field             | Type   | Required | Description                                                                      |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `input`           | string | Yes      | Natural-language request describing the agent to create, up to 256 KB serialized |
| `conversation_id` | UUID   | No       | Existing creation conversation to continue                                       |
| `webhook_url`     | string | No       | Public `http` or `https` URL for the terminal result                             |

Returns `202 Accepted` with a queued `run_id`, `conversation_id`, and `agent_id: null`. Poll `GET /v1/runs/:run_id`; when the creation run completes, the response includes the new agent ID in both `agent_id` and `result.agent_id`.

### Update an agent

```
PATCH /v1/agents/:agent_id
```

Update an agent by replacing provided fields. Omitted fields are unchanged; this endpoint does not interpret natural-language instructions. The body can include any supported create field plus optional `release_note`. The target must be a personal agent owned by the Account key owner. Team, shared, deleted, or foreign agents return `AGENT_NOT_FOUND`.

### Edit an agent from instructions

```
POST /v1/agents/:agent_id/edits
```

Start an async natural-language edit for an agent. Use this when your product wants to say what should change, for example:

```json theme={null}
{
  "instructions": "Add a valuation sensitivity table for the selected ticker and include a short downside-risk note.",
  "release_note": "Add valuation sensitivity section."
}
```

Returns `202 Accepted` with `run_id`, `agent_id`, `status`, and timestamps. Poll `GET /v1/agents/:agent_id/edits/:run_id` until `status` is `succeeded`, `failed`, or `cancelled`.

### Create an async run

```
POST /v1/runs
```

#### JSON body

| Field             | Type   | Required | Description                                                     |
| ----------------- | ------ | -------- | --------------------------------------------------------------- |
| `agent_id`        | UUID   | Yes      | Active personal CREAO agent to run                              |
| `input`           | JSON   | Yes      | Structured input for the agent, up to 256 KB serialized         |
| `conversation_id` | UUID   | No       | Reuse an existing Developer Platform conversation/thread        |
| `webhook_url`     | string | No       | Public `http` or `https` URL to receive the terminal run result |

Returns `202 Accepted` with a run object.

### Get run status

```
GET /v1/runs/:run_id
```

Returns the run object for the authenticated Account key owner.

| Field                  | Type           | Description                                                 |
| ---------------------- | -------------- | ----------------------------------------------------------- |
| `run_id`               | UUID           | Run ID                                                      |
| `status`               | string         | `pending`, `running`, `completed`, `failed`, or `cancelled` |
| `agent_id`             | UUID           | Agent that ran                                              |
| `conversation_id`      | UUID \| null   | Conversation/thread ID for follow-up runs                   |
| `result`               | JSON           | Final agent output, present after completion                |
| `usage.credits`        | number         | Credits used by the run, when available                     |
| `error.code`           | string         | Machine-readable failure code, when failed                  |
| `created_at`           | string         | ISO timestamp for run creation                              |
| `started_at`           | string \| null | ISO timestamp for execution start                           |
| `completed_at`         | string \| null | ISO timestamp for terminal status                           |
| `webhook_delivered_at` | string \| null | ISO timestamp for successful webhook delivery               |

### List runs

```
GET /v1/runs?status=completed&limit=20&offset=0
```

Query parameters:

| Parameter | Default | Max   | Description                                                           |
| --------- | ------- | ----- | --------------------------------------------------------------------- |
| `status`  | -       | -     | Filter by `pending`, `running`, `completed`, `failed`, or `cancelled` |
| `limit`   | `20`    | `100` | Number of runs to return                                              |
| `offset`  | `0`     | -     | Number of runs to skip                                                |

Response:

```json theme={null}
{
  "runs": [],
  "limit": 20,
  "offset": 0
}
```

## Realtime runs

Use Developer Platform realtime runs when your backend wants streamed progress and output.

```
POST /v1/realtime/runs
```

Body fields:

| Field             | Type | Required | Description                                              |
| ----------------- | ---- | -------- | -------------------------------------------------------- |
| `agent_id`        | UUID | Yes      | Active personal CREAO agent to run                       |
| `input`           | JSON | Yes      | Structured input for the agent, up to 256 KB serialized  |
| `conversation_id` | UUID | No       | Reuse an existing Developer Platform conversation/thread |

Example:

```bash theme={null}
curl -N -X POST https://developer.creao.ai/v1/realtime/runs \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-000000000000",
    "input": { "query": "Summarize the latest quarterly report" }
  }'
```

The response is `text/event-stream`. Events include:

| Event               | Meaning                                       |
| ------------------- | --------------------------------------------- |
| `run.created`       | Run record and conversation have been created |
| `message.created`   | A new assistant message started               |
| `output_text.delta` | Incremental text output                       |
| `tool.started`      | A tool call started                           |
| `tool.completed`    | A tool call completed                         |
| `artifact.created`  | An artifact was produced                      |
| `run.completed`     | Run finished successfully                     |
| `run.failed`        | Run failed                                    |
| `error`             | Stream-level error                            |
| `ping`              | Keepalive event                               |

## Conversations

Pass a previous `conversation_id` to continue the same thread of work with the same agent through Developer Platform:

```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",
    "conversation_id": "22222222-2222-4222-8222-222222222222",
    "input": { "follow_up": "Turn that into a slide outline" }
  }'
```

## Webhooks

Developer Platform async runs can deliver the terminal result to your backend:

```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": { "query": "quarterly revenue" },
    "webhook_url": "https://your-server.example/webhooks/creao"
  }'
```

<Warning>
  `webhook_url` must be a publicly reachable `http` or `https` URL. URLs pointing to private networks are rejected.
</Warning>

## Keep request shapes separate

Do not mix the two route families:

| App-scoped API Trigger           | Developer Platform API            |
| -------------------------------- | --------------------------------- |
| `Authorization: Bearer capi_...` | `Authorization: Bearer cr_sk_...` |
| `POST /api/v1/apps/{appId}/runs` | `POST /v1/runs`                   |
| URL-scoped `appId`               | Body field `agent_id`             |
| Body field `inputs`              | Body field `input`                |
| Agent-page key management        | Developer Console key management  |

## Rate limits

Developer Platform requests are account-scoped and enforced before execution starts. The Developer Console dashboard shows your plan, available credits, and active rate limit.