API Trigger

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.

For the Developer Platform endpoint reference, see the API Reference. For a side-by-side contract summary, see API Paths.

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.

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

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:

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

Poll a run

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. Developer Platform keys start with cr_sk_ and are sent as Bearer tokens to developer.creao.ai/v1/*.

Create an Account API key

Open Developer Console, go to API Keys, and create a key. Store the full key immediately because it is shown only once.

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.

Create an async run

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:

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

Poll for the result

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.

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:

{
  "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:

{
  "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:

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:

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:

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

webhook_url must be a publicly reachable http or https URL. URLs pointing to private networks are rejected.

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.

Get Started

Features

Agent Brain

Advanced

Trust & Safety

Overview

Which path should I use?

App-scoped API Trigger

Create a run

Poll a run

Developer Platform API

Developer Platform reference

Create an agent

JSON body

Update an agent

Edit an agent from instructions

Create an async run

JSON body

Get run status

List runs

Realtime runs

Conversations

Webhooks

Keep request shapes separate

Rate limits

​Overview

​Which path should I use?

​App-scoped API Trigger

​Create a run

​Poll a run

​Developer Platform API

​Developer Platform reference

​Create an agent

​JSON body

​Update an agent

​Edit an agent from instructions

​Create an async run

​JSON body

​Get run status

​List runs

​Realtime runs

​Conversations

​Webhooks

​Keep request shapes separate

​Rate limits

Overview

Which path should I use?

App-scoped API Trigger

Create a run

Poll a run

Developer Platform API

Developer Platform reference

Create an agent

JSON body

Update an agent

Edit an agent from instructions

Create an async run

JSON body

Get run status

List runs

Realtime runs

Conversations

Webhooks

Keep request shapes separate

Rate limits