Skip to main content

​
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.
Early Access — API Trigger is currently available to select users. To request access, reach out to us on Discord and mention you’d like to try the API.
This is a Pro feature. API key creation requires a paid plan (Pro or higher).

​
Getting started

1

Create an API key

Open Account Settings → API Keys and click Create key. Give it a name (e.g., “Production” or “CI/CD”) and copy the key immediately — it’s only shown once.Your key starts with capi_ and acts as a Bearer token for all API requests.
2

Find your app ID

Open the agent app you want to trigger. The app ID is in the URL:
https://agent.creao.ai/apps/<app-id>
You can also find it via the API:
curl https://agent.creao.ai/api/agentapps \
  -H "Authorization: Bearer capi_your_key_here"
3

Trigger a run

Send a POST request with your app ID and inputs:
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"
    }
  }'
You’ll get an immediate response with a run ID:
{
  "id": "run-uuid",
  "status": "pending",
  "appId": "your-app-id",
  "appName": "Your App Name"
}
4

Poll for the result

The agent runs asynchronously. Poll the run endpoint until the status changes to completed:
curl https://agent.creao.ai/api/v1/runs/run-uuid \
  -H "Authorization: Bearer capi_your_key_here"
A completed run includes the agent’s structured output and any generated artifacts:
{
  "id": "run-uuid",
  "status": "completed",
  "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"
      }
    ]
  },
  "startedAt": "2026-04-27T07:01:11Z",
  "completedAt": "2026-04-27T07:03:00Z"
}

​
API reference

​
Create a run

POST /api/v1/runs
FieldTypeRequiredDescription
appIdstringYesThe agent app to run
inputsobjectNoKey-value pairs matching the app’s input fields
chatModelIdstringNoOverride the default LLM model
webhookUrlstringNoURL to receive a POST callback when the run completes
Returns 202 Accepted with { id, status, appId, appName }.

​
Get run status

GET /api/v1/runs/:id
Returns the full run object including status, result, artifacts, startedAt, and completedAt.

​
List runs

GET /api/v1/runs?status=completed&limit=20&offset=0
Returns a paginated list of your recent API runs. Filter by status (pending, running, completed, failed, cancelled).

​
Cancel a run

POST /api/v1/runs/:id/cancel
Cancels a pending or running agent. Returns { success: true }.

​
Run lifecycle

Every API-triggered run goes through these states:
StatusMeaning
pendingRequest accepted, agent starting up
runningAgent is executing inside the sandbox
completedAgent finished successfully — result available
failedAgent encountered an error — check errorCode
cancelledYou 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.

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

​
Managing API keys

You can manage your keys in Account Settings → API Keys:
  • Create up to 10 active keys per account
  • Revoke any key instantly — revoked keys stop working immediately
  • Track usage — each key shows when it was last used
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 user. 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.