Developer API Quickstart

Before you start

Use this guide when your backend calls the CREAO Developer API directly.

Requirement	Value
Product surface	Developer Console
Base URL	`https://developer.creao.ai`
Auth key	Account API key starting with `cr_sk_`
Caller	Your server, worker, queue consumer, or backend job
Main run route	`POST /v1/runs`

Never send a cr_sk_ Account API key to browser frontend code, mobile apps, public repositories, analytics events, or client logs.

If you are using agent.creao.ai in the browser, start with Using CREAO. If you need an app-scoped key for one browser-created agent, see API Trigger. This page covers the Developer Platform /v1/* API.

1. Create an Account API key

Open Developer Console, go to API Keys, and create an Account API key. Store it in your backend secret manager. For local testing, set it as an environment variable:

export CREAO_API_KEY="cr_sk_your_key_here"

2. Create or choose an agent

You can create a personal agent through the API, or copy an existing agent_id from Developer Console. If you already have an agent ID, skip to step 3. POST /v1/agents starts an asynchronous creation run from a natural-language request:

curl -X POST https://developer.creao.ai/v1/agents \
  -H "Authorization: Bearer $CREAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Create a personal agent named Stock Analysis Agent that accepts ticker and reporting_period inputs and builds a concise stock analysis memo from public filings and price history."
  }'

The API returns 202 Accepted with a creation run_id. The agent_id remains null while CREAO builds the agent:

{
  "run_id": "33333333-3333-4333-8333-333333333333",
  "status": "pending",
  "agent_id": null,
  "conversation_id": "44444444-4444-4444-8444-444444444444"
}

Poll the creation run before continuing:

curl https://developer.creao.ai/v1/runs/33333333-3333-4333-8333-333333333333 \
  -H "Authorization: Bearer $CREAO_API_KEY"

When the run completes, store the new ID from agent_id or result.agent_id:

{
  "run_id": "33333333-3333-4333-8333-333333333333",
  "status": "completed",
  "agent_id": "00000000-0000-4000-8000-000000000000",
  "conversation_id": "44444444-4444-4444-8444-444444444444",
  "result": {
    "agent_id": "00000000-0000-4000-8000-000000000000",
    "agent_name": "Stock Analysis Agent"
  }
}

See Create an agent for the complete request and response contract.

3. Start an async run

Use async runs for jobs that can finish in the background. Store the returned run_id and conversation_id.

curl -X POST https://developer.creao.ai/v1/runs \
  -H "Authorization: Bearer $CREAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-000000000000",
    "input": {
      "ticker": "AAPL",
      "reporting_period": "2025 Q4"
    },
    "model": "anthropic/claude-haiku-4-5"
  }'

Omit model to use the default model, currently anthropic/claude-sonnet-5. See Models to compare supported ids and account-specific availability.

{
  "run_id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "agent_id": "00000000-0000-4000-8000-000000000000",
  "conversation_id": "22222222-2222-4222-8222-222222222222",
  "model": "anthropic/claude-haiku-4-5"
}

4. Poll for completion

Poll GET /v1/runs/{run_id} until the status is terminal.

curl https://developer.creao.ai/v1/runs/11111111-1111-4111-8111-111111111111 \
  -H "Authorization: Bearer $CREAO_API_KEY"

Terminal statuses are completed, failed, and cancelled.

{
  "run_id": "11111111-1111-4111-8111-111111111111",
  "status": "completed",
  "agent_id": "00000000-0000-4000-8000-000000000000",
  "conversation_id": "22222222-2222-4222-8222-222222222222",
  "model": "anthropic/claude-haiku-4-5",
  "result": {
    "text": "Stock analysis memo..."
  },
  "usage": {
    "credits": 12
  }
}

5. Continue context

Pass a previous conversation_id when follow-up runs should share context with earlier work.

curl -X POST https://developer.creao.ai/v1/runs \
  -H "Authorization: Bearer $CREAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-000000000000",
    "conversation_id": "22222222-2222-4222-8222-222222222222",
    "input": {
      "ticker": "AAPL",
      "reporting_period": "2025 Q4",
      "follow_up": "Add a downside-risk section and summarize the key valuation assumptions."
    }
  }'

conversation_id is opaque and account-scoped. Store your own user, tenant, or workflow ID next to it in your database.

6. Choose a model

Pass an optional model field on POST /v1/runs, POST /v1/realtime/runs, POST /v1/agents, and POST /v1/agents/{agent_id}/edits to control which AI model handles that request. Omit it to use the account default.

curl -X POST https://developer.creao.ai/v1/runs \
  -H "Authorization: Bearer $CREAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-000000000000",
    "input": { "ticker": "AAPL", "reporting_period": "2025 Q4" },
    "model": "anthropic/claude-opus-4-8"
  }'

Call GET /v1/models to list available models along with pricing tier, whether a paid plan is required, and whether it’s currently available for your account:

curl https://developer.creao.ai/v1/models \
  -H "Authorization: Bearer $CREAO_API_KEY"

The run response echoes the resolved model back so you can confirm which one handled the request.

Realtime streaming

Use POST /v1/realtime/runs when your product needs live output over Server-Sent Events instead of polling.

curl -N -X POST https://developer.creao.ai/v1/realtime/runs \
  -H "Authorization: Bearer $CREAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-000000000000",
    "input": {
      "ticker": "AAPL",
      "reporting_period": "2025 Q4"
    },
    "model": "anthropic/claude-haiku-4-5"
  }'

The stream emits typed events such as run.created, output_text.delta, artifact.created, run.completed, run.failed, and error. See Streaming Events.

Webhooks

For async runs, include webhook_url when your backend should receive the terminal result.

curl -X POST https://developer.creao.ai/v1/runs \
  -H "Authorization: Bearer $CREAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-000000000000",
    "input": { "ticker": "AAPL", "reporting_period": "2025 Q4" },
    "webhook_url": "https://api.example.com/webhooks/creao"
  }'

Your webhook endpoint should accept duplicate terminal notifications and verify that the run_id belongs to a request your system created. Polling remains the fallback if delivery fails. See Webhooks.

Production checklist

Keep cr_sk_ keys in a server-side secret store.
Store agent_id, run_id, and conversation_id as separate identifiers.
Treat conversation_id as opaque; do not parse it or use it as your user ID.
Retry 429 responses only after Retry-After when the header is present.
Use idempotency in your own queue or job table before creating non-idempotent runs.
Map stable error codes from Errors, not English messages.
Use Rate Limits and Developer Console to understand account-level throughput.

Get Started

Agents

Agent Memory

Agent Files

Runs

Models

Workspaces

Workspace Files

Secrets

Skills

Concepts

Before you start

1. Create an Account API key

2. Create or choose an agent

3. Start an async run

4. Poll for completion

5. Continue context

6. Choose a model

Realtime streaming

Webhooks

Production checklist

​Before you start

​1. Create an Account API key

​2. Create or choose an agent

​3. Start an async run

​4. Poll for completion

​5. Continue context

​6. Choose a model

​Realtime streaming

​Webhooks

​Production checklist

Before you start

1. Create an Account API key

2. Create or choose an agent

3. Start an async run

4. Poll for completion

5. Continue context

6. Choose a model

Realtime streaming

Webhooks

Production checklist