API Trigger - CREAO Documentation

Overview

The API Trigger feature lets you run your agent apps from external scripts, CI/CD pipelines, or other applications — no browser required. Create an API key, point it at any agent app, pass inputs, and get structured results back.

API runs consume credits from your account balance, the same as running an agent from the UI.

Getting started

Create an API key

There are two ways to create a key:Option A — Per-app key: Open the agent app you want to trigger, click the API Trigger button in the top toolbar, then click + Create. Give it a name (e.g., “Production”). The key is automatically scoped to that app — it can only trigger runs for that specific app. The example curl command is pre-filled with the correct endpoint.Option B — Account-wide key: Open Account Settings → API Keys and click + Create key. Give it a name. Account-wide keys can trigger any of your apps by passing appId in the request body. In the key list, app-scoped keys display a badge linking to their associated app.Either way, the key starts with capi_, is sent as a Bearer token, and is shown only once — copy it immediately.

Trigger a run

Using a per-app key (app ID is in the URL — no appId needed in the body):

curl -X POST https://agent.creao.ai/api/v1/apps/your-app-id/runs \
  -H "Authorization: Bearer capi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"company": "Apple", "year": "2025"}}'

Using an account-wide key (pass appId in the request body):

curl -X POST https://agent.creao.ai/api/v1/runs \
  -H "Authorization: Bearer capi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "your-app-id",
    "inputs": {
      "company": "Apple",
      "year": "2025"
    }
  }'

With file attachments — use multipart/form-data and repeat -F files=@... for each file:

curl -X POST https://agent.creao.ai/api/v1/apps/your-app-id/runs \
  -H "Authorization: Bearer capi_your_key_here" \
  -F 'inputs={"query": "summarize this report"}' \
  -F "files=@/path/to/report.pdf" \
  -F "files=@/path/to/data.csv"

All variants return 202 Accepted with an immediate response containing a run ID:

{
  "id": "run-uuid",
  "status": "pending",
  "appId": "your-app-id",
  "appName": "Your App Name"
}

Poll for the result

The agent runs asynchronously. Poll until the status changes to completed.Per-app endpoint:

curl https://agent.creao.ai/api/v1/apps/your-app-id/runs/run-uuid \
  -H "Authorization: Bearer capi_your_key_here"

Account-wide endpoint:

curl https://agent.creao.ai/api/v1/runs/run-uuid \
  -H "Authorization: Bearer capi_your_key_here"

A completed run response:

{
  "id": "run-uuid",
  "status": "completed",
  "threadId": "thread-uuid",
  "result": {
    "text": "{\"ticker\": \"AAPL\", \"annual_return_pct\": \"12.49\"}",
    "artifacts": [
      {
        "type": "image/png",
        "title": "aapl_2025_stock.png"
      },
      {
        "type": "text/markdown",
        "title": "AAPL Stock 2025 Performance Report"
      }
    ]
  },
  "errorCode": null,
  "startedAt": "2026-04-27T07:01:11Z",
  "completedAt": "2026-04-27T07:03:00Z",
  "createdAt": "2026-04-27T07:01:10Z"
}

If the run failed, status is "failed" and errorCode contains a machine-readable reason.

API reference

Create a run

Per-app alias — best paired with a per-app key. The URL appId always wins over any appId in the body.

POST /api/v1/apps/:appId/runs

Account-wide — works with any account-level key; appId must be in the body.

POST /api/v1/runs

Both endpoints accept either application/json or multipart/form-data. Use multipart when you need to attach files.

JSON body

Field	Type	Required	Description
`appId`	string	Yes (account-wide only)	The agent app to run
`inputs`	object	No	Key-value pairs matching the app’s input fields
`chatModelId`	string	No	Override the default LLM model
`workspaceId`	string	No	Associate the run with a specific workspace
`webhookUrl`	string	No	URL to receive a POST callback when the run completes

Multipart form fields

Use Content-Type: multipart/form-data when you want to attach files alongside run parameters.

Field	Type	Required	Description
`appId`	text	Yes (account-wide only)	The agent app to run
`inputs`	text (JSON string)	No	JSON-encoded object of key-value pairs
`chatModelId`	text	No	Override the default LLM model
`workspaceId`	text	No	Associate the run with a specific workspace
`webhookUrl`	text	No	URL to receive a POST callback when the run completes
`files`	file	No	One or more files to pass to the agent (repeat the field for multiple files)

File constraints: up to 10 files per run, 10 MB per file. Accepted types include images, PDFs, text, spreadsheets, code files, audio, video, and more (see accepted file types). Returns 202 Accepted with { id, status, appId, appName }.

Get run status

Per-app alias:

GET /api/v1/apps/:appId/runs/:runId

Account-wide:

GET /api/v1/runs/:id

Returns the full run object. Fields:

Field	Type	Description
`id`	string	Run UUID
`status`	string	Current run state (see Run lifecycle)
`threadId`	string \| null	Chat thread ID, available once the agent starts
`result`	object \| null	Agent output, available when `status` is `completed`
`errorCode`	string \| null	Machine-readable error code when `status` is `failed`
`startedAt`	string \| null	ISO 8601 timestamp when the agent started
`completedAt`	string \| null	ISO 8601 timestamp when the run ended
`createdAt`	string	ISO 8601 timestamp when the run was created

List runs

Per-app (returns only runs for that app):

GET /api/v1/apps/:appId/runs?status=completed&limit=20&offset=0

Account-wide (returns all your runs):

GET /api/v1/runs?status=completed&limit=20&offset=0

Query parameters:

Parameter	Default	Max	Description
`status`	—	—	Filter by status: `pending`, `running`, `completed`, `failed`, or `cancelled`
`limit`	`20`	`100`	Number of results to return
`offset`	`0`	—	Number of results to skip (for pagination)

Response:

{
  "runs": [ /* array of run objects */ ],
  "limit": 20,
  "offset": 0
}

Cancel a run

POST /api/v1/runs/:id/cancel

Cancels a pending or running agent. Returns { "success": true }. Returns an error if the run is already completed, failed, or cancelled.

Attaching files

You can attach files to any API run by sending the request as multipart/form-data. The agent receives the files as local disk paths inside its sandbox and can read them with Bash, Python, or any other tool.

# Attach a single PDF
curl -X POST https://agent.creao.ai/api/v1/apps/your-app-id/runs \
  -H "Authorization: Bearer capi_your_key_here" \
  -F 'inputs={"task": "extract key metrics"}' \
  -F "files=@report.pdf"

# Attach multiple files (repeat -F files=@ for each)
curl -X POST https://agent.creao.ai/api/v1/runs \
  -H "Authorization: Bearer capi_your_key_here" \
  -F "appId=your-app-id" \
  -F 'inputs={"task": "compare these datasets"}' \
  -F "files=@sales_q1.csv" \
  -F "files=@sales_q2.csv"

The same endpoints work with any HTTP client. In Python:

import requests

resp = requests.post(
    "https://agent.creao.ai/api/v1/apps/your-app-id/runs",
    headers={"Authorization": "Bearer capi_your_key_here"},
    data={"inputs": '{"task": "summarize"}'},
    files=[
        ("files", ("report.pdf", open("report.pdf", "rb"), "application/pdf")),
        ("files", ("data.csv",   open("data.csv",   "rb"), "text/csv")),
    ],
)
run = resp.json()

Limits:

Up to 10 files per run
Up to 10 MB per file
Empty files are rejected

Accepted file types

Images (PNG, JPG, GIF, WebP, HEIC, SVG, …), PDF, plain text, Markdown, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), CSV, HTML, JSON, YAML, XML, common code extensions (.py, .js, .ts, .go, .rb, .java, .sh, .sql, …), archives (.zip), audio (MP3, WAV, M4A, FLAC, …), and video (MP4, WebM, MOV).

Run lifecycle

Every API-triggered run goes through these states:

Status	Meaning
`pending`	Request accepted, agent starting up
`running`	Agent is executing inside the sandbox
`completed`	Agent finished successfully — `result` is available
`failed`	Agent encountered an error — check `errorCode`
`cancelled`	You cancelled the run via the cancel endpoint

Runs typically take 30 seconds to 3 minutes depending on the agent app’s complexity.

Webhooks

Instead of polling, you can provide a webhookUrl to receive the result automatically:

curl -X POST https://agent.creao.ai/api/v1/runs \
  -H "Authorization: Bearer capi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "your-app-id",
    "inputs": { "query": "quarterly revenue" },
    "webhookUrl": "https://your-server.com/webhook"
  }'

When the run completes, your server receives a POST with the run result. The webhook retries up to 3 times with exponential backoff if your server doesn’t respond with a 2xx status.

webhookUrl must be a publicly reachable http or https URL. URLs pointing to private networks are rejected with a 400 error.

Viewing API runs in the UI

API-triggered runs appear in the agent app’s Runs tab with an [API] prefix. Click any run to open the full chat thread and see the agent’s step-by-step work, including tool calls, web searches, and generated artifacts. You can also navigate to any run thread directly using the threadId field from the run response.

Managing API keys

Per-app keys are created and managed directly from the app’s API Trigger panel. Each key is scoped to a single app and can only trigger runs for it. Attempting to use a per-app key against a different app returns 403 APP_SCOPE_RESTRICTED. Account-wide keys are managed in Account Settings → API Keys. They can be used with any of your apps. Keys that were originally created as per-app keys appear with an app badge in the key list. Both key types:

Revoke any key instantly — revoked keys stop working immediately
Track usage — each key shows its creation date and last-used date

API keys are shown only once when created. Store them securely — treat them like passwords. If a key is compromised, revoke it immediately from the API Keys settings.

Rate limits

API requests are rate-limited to 30 requests per minute per key. If you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.

Credits

API runs consume credits from your account balance, the same as running an agent from the UI. Credit usage depends on the LLM model and the complexity of the agent’s work.

​Overview

​Getting started

​API reference

​Create a run

​JSON body

​Multipart form fields

​Get run status

​List runs

​Cancel a run

​Attaching files

​Accepted file types

​Run lifecycle

​Webhooks

​Viewing API runs in the UI

​Managing API keys

​Rate limits

​Credits

Overview

Getting started

API reference

Create a run

JSON body

Multipart form fields

Get run status

List runs

Cancel a run

Attaching files

Accepted file types

Run lifecycle

Webhooks

Viewing API runs in the UI

Managing API keys

Rate limits

Credits