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

> Run CREAO agents from your backend through the Developer Platform v1 API.

## Developer Platform API

The CREAO Developer Platform API lets you create, update, and run personal CREAO agents from your backend services. Use it for automation jobs, product workflows, internal tools, and user-facing experiences that need a hosted cloud agent runtime.

Developer API v1 is served from:

```text theme={null}
https://developer.creao.ai
```

All public API routes use Account API keys from Developer Console. Keys start with `cr_sk_` and are sent as bearer tokens.

<Note>
  CREAO also supports app-scoped API Trigger keys created from an agent detail page in `agent.creao.ai`. Those keys start with `capi_` and call `agent.creao.ai/api/v1/apps/{appId}/runs`. This API Reference covers the Developer Platform `/v1/*` endpoints; see [API Trigger](/pro/api-trigger) and [API Paths](/api-reference/api-paths) for the side-by-side model.
</Note>

## What you can build

* **Background automation** - run agents for reports, research, monitoring, and content operations.
* **Product features** - stream agent output into your own product with realtime runs.
* **Backend integrations** - trigger existing CREAO agents from scripts, CI jobs, queues, and webhooks.
* **Reusable workflows** - keep agent setup, runtime state, tools, and files inside CREAO while your app sends structured inputs.

## Core concepts

| Concept           | Meaning                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| Account API key   | Server-side key from Developer Console. Keys start with `cr_sk_`.                                         |
| `agent_id`        | Personal CREAO agent you own. Create one through `/v1/agents` or copy it from Developer Console > Agents. |
| `run_id`          | Developer API run record. Use it to fetch status, result, usage, and errors.                              |
| `conversation_id` | Opaque CREAO conversation ID. Reuse it to continue context across runs.                                   |

## Run modes

<CardGroup cols={2}>
  <Card title="Async runs" icon="clock" href="/api-reference/runs/create-async-run">
    Create background runs with `POST /v1/runs`, poll by `run_id`, list recent runs, or receive terminal webhooks.
  </Card>

  <Card title="Realtime runs" icon="radio" href="/api-reference/runs/create-realtime-run">
    Create streamed runs with `POST /v1/realtime/runs` and consume typed Server-Sent Events.
  </Card>

  <Card title="Agent management" icon="bot" href="/api-reference/agents/create-agent">
    Create agents, replace provided fields, or request natural-language edits before running them by `agent_id`.
  </Card>
</CardGroup>

## Start here

<Steps>
  <Step title="Create an Account API key">
    Open [Developer Console](https://developer.creao.ai/), go to **API Keys**, and create a server-side Account API key.
  </Step>

  <Step title="Create or copy an agent ID">
    Create a personal agent with `POST /v1/agents`, or open **Agents** in Developer Console and copy the `agent_id` for an existing active personal agent.
  </Step>

  <Step title="Create a 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": { "query": "Create a weekly sales summary" }
      }'
    ```
  </Step>
</Steps>

<Warning>
  Account API keys are server-side secrets. Do not put them in browser frontend code or mobile apps.
</Warning>

## API behavior

<CardGroup cols={2}>
  <Card title="Authentication" icon="key-round" href="/api-reference/authentication">
    Create keys, send bearer tokens, rotate secrets, and understand account-level scope.
  </Card>

  <Card title="Conversations" icon="messages-square" href="/api-reference/conversations">
    Reuse `conversation_id` values to continue context across async and realtime runs.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Receive terminal async run results at your backend.
  </Card>

  <Card title="Errors and rate limits" icon="circle-alert" href="/api-reference/errors">
    Handle stable error codes, retry headers, and credit-related failures.
  </Card>

  <Card title="API Paths" icon="route" href="/api-reference/api-paths">
    Compare app-scoped API Trigger keys with Developer Platform Account API keys.
  </Card>
</CardGroup>