API Paths

Two supported paths

CREAO supports two API paths for running agents:

Path	Key prefix	Base URL	Request identity	Input field
App-scoped API Trigger	`capi_`	`https://agent.creao.ai/api/v1/apps/{appId}`	`appId` in the URL	`inputs`
Developer Platform API	`cr_sk_`	`https://developer.creao.ai/v1`	Account-owned `agent_id`	`input`

Both are current supported paths. They serve different product entry points and keep separate key scopes, route families, and request shapes.

App-scoped API Trigger

Use this path when you want a key that can only run one specific agent. Create the key from the agent detail page in agent.creao.ai.

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": { "topic": "weekly report" }
  }'

If your platform cannot set a custom Authorization header, pass the key as a creao-api-key query parameter instead. The header always takes precedence when both are present.

curl -X POST "https://agent.creao.ai/api/v1/apps/00000000-0000-4000-8000-000000000000/runs?creao-api-key=capi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": { "topic": "weekly report" }
  }'

Prefer the Authorization header whenever possible. A key passed via query parameter can be captured in infrastructure access logs (e.g. CDN/load-balancer request logs), browser history, and referrer headers — sinks the header form avoids. Only use the query parameter when your platform genuinely cannot set a custom header, and rotate keys used this way more frequently.

Developer Platform API

Use this path when your backend needs account-level agent lifecycle management, async run records, realtime SSE, webhooks, or usage analytics. Create the key in Developer Console.

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": { "ticker": "AAPL", "reporting_period": "2025 Q4" }
  }'

Contract comparison

Concern	App-scoped API Trigger	Developer Platform API
Key creation	Agent detail page in `agent.creao.ai`	Developer Console
Key scope	One agent	Account-owned personal agents
Key prefix	`capi_`	`cr_sk_`
Agent create route	Not supported	`POST /v1/agents` starts an async natural-language creation run
Agent update route	Not supported	`PATCH /v1/agents/{agent_id}` replaces provided fields
Agent edit route	Not supported	`POST /v1/agents/{agent_id}/edits` starts a natural-language edit
Agent edit status	Not supported	`GET /v1/agents/{agent_id}/edits/{run_id}`
Agent memory	Not supported	`GET` / `PUT` / `DELETE /v1/agents/{agent_id}/memory`
Agent files	Not supported	`GET` / `DELETE /v1/agents/{agent_id}/files...`
Workspace files	Not supported	`GET` / `POST` / `DELETE /v1/workspaces/{workspace_id}/files...`
Workspaces	Not supported	`GET` / `POST /v1/workspaces` and assign/unassign agents
Secrets	Not supported	`GET` / `POST /v1/secrets` and `PATCH` / `DELETE /v1/secrets/{name}` (values never returned)
Skills	Not supported	`GET` / `POST /v1/skills` and enable / disable / refresh by `skill_id` (account-level Agent Brain skills; not injected into `/v1/runs`)
Async create route	`POST /api/v1/apps/{appId}/runs`	`POST /v1/runs`
Status route	`GET /api/v1/apps/{appId}/runs/{runId}`	`GET /v1/runs/{run_id}`
List route	`GET /api/v1/apps/{appId}/runs`	`GET /v1/runs`
Realtime SSE	Not exposed on this path	`POST /v1/realtime/runs`
Model discovery	Not supported	`GET /v1/models`
Webhooks	Supported by app-run request body	Supported by `webhook_url`
Conversation reuse	App-run/thread semantics	`conversation_id`
Request body	`inputs`, plus app-run options	`agent_id`, `input`, optional `model`, optional `conversation_id`, optional `workspace_id`, optional `webhook_url`

Keep route families separate

Do not send Developer Platform request bodies to agent.creao.ai/api/v1/*, and do not send app-scoped request bodies to developer.creao.ai/v1/*. For example, /v1/runs expects agent_id and input, not appId or inputs. The app-scoped path already has the agent id in the URL and expects inputs.

Get Started

Agents

Agent Memory

Agent Files

Runs

Models

Workspaces

Workspace Files

Secrets

Skills

Concepts

Two supported paths

App-scoped API Trigger

Developer Platform API

Contract comparison

Keep route families separate

​Two supported paths

​App-scoped API Trigger

​Developer Platform API

​Contract comparison

​Keep route families separate

Two supported paths

App-scoped API Trigger

Developer Platform API

Contract comparison

Keep route families separate