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. 
curl -X POST https://developer.creao.ai/v1/agents \
  -H "Authorization: Bearer $CREAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stock Analysis Agent",
    "description": "Builds a stock analysis memo from public filings and price history.",
    "skill_content": "# Stock Analysis Agent\n\nBuild a concise stock analysis memo from the provided ticker, company, and reporting period.",
    "config": {
      "inputs": {
        "ticker": { "type": "string" },
        "reporting_period": { "type": "string" }
      }
    },
    "write_autonomy": "full_auto"
  }'
The response includes an agent_id: 
{
  "agent_id": "00000000-0000-4000-8000-000000000000",
  "name": "Stock Analysis Agent",
  "status": "active"
}

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