Skip to main content

​
Before you start

Use this guide when your backend calls the CREAO Developer API directly.
RequirementValue
Product surfaceDeveloper Console
Base URLhttps://developer.creao.ai
Auth keyAccount API key starting with cr_sk_
CallerYour server, worker, queue consumer, or backend job
Main run routePOST /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"
    }
  }'

{
  "run_id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "agent_id": "00000000-0000-4000-8000-000000000000",
  "conversation_id": "22222222-2222-4222-8222-222222222222"
}

​
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",
  "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.

​
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"
    }
  }'
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.