Skip to main content

​
Custom HTTP & scripts

Use any HTTP client (curl, scripts, backend jobs) with the Agent API. You need the same Credentials as n8n or Zapier: Agent ID, workspace API key, and your deployment base URL (no trailing slash on the host).

​
Headers on every call

HeaderValue
X-Agent-IdYour agent UUID
X-Api-KeyYour workspace API key
Content-Typeapplication/json (for POST)

​
Create an approval (curl)

Replace placeholders and run: 
export BASE_URL="https://your-api.example.com"
export AGENT_ID="00000000-0000-0000-0000-000000000000"
export API_KEY="your-workspace-api-key"

curl -sS -X POST "$BASE_URL/v1/approvals" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: $AGENT_ID" \
  -H "X-Api-Key: $API_KEY" \
  -d '{
    "question": "Deploy to production?",
    "context_markdown": "Build #123 passed CI.",
    "options": [
      { "label": "Approve", "value": "approve" },
      { "label": "Reject", "value": "reject" }
    ]
  }'
The JSON response includes request_id (use this for polling, even if you did not send request_id in the body). Optional fields (timeout, callback, request_id, …) are documented under POST /v1/approvals.

​
Poll for the result (curl)

export REQUEST_ID="<request_id from create response>"

curl -sS "$BASE_URL/v1/approvals/$REQUEST_ID/result" \
  -H "X-Agent-Id: $AGENT_ID" \
  -H "X-Api-Key: $API_KEY"
While humans have not finished, the body looks like { "request_id": "...", "status": "pending" }. When resolved, status is no longer pending and the payload includes outcome fields—see GET result and Approval status values.

​
Callback instead of polling

If you set callback.url on create, the service POSTs the same JSON as the final poll response when the approval completes. See Callback webhooks.

​
Errors to handle

  • 400 invalid_payload — Fix the JSON; check issues if present.
  • 401 — Wrong agent or API key.
  • 403 USAGE_APPROVAL_LIMIT — Plan / usage cap; see Automation limits & billing.
  • 409 idempotency_conflict — Same request_id with a different payload.
  • 429 rate_limited — Slow down creates; see Rate limits.