API Reference

Cody API

Start and control agent runs, observe their progress, and coordinate delegated work over a simple HTTPS API.

Base URLhttps://api.agentcody.ai/codyapi

Introduction

The Cody API gives your integrations a direct line to your agents. Send an agent a task, get back a runId, and poll until it finishes. While it runs, you can consume incremental events, steer the active turn, cancel it, or attach child runs to build a traceable delegation tree.

Every request is scoped to your account by its API key and routed to your own dedicated Cody instance. Calls never touch another customer's data.

Authentication

Authenticate every request with a secret API key in the Authorization header as a Bearer token. Keys look like cody_sk_….

Generate and manage keys in the dashboard under Tools → Cody API. Treat them like passwords — the full key is shown only once, and you can revoke a key at any time.

Authorization: Bearer cody_sk_your_key_here

Base URL

All endpoints share a single base URL. The action is selected by HTTP method and an optional query.

https://api.agentcody.ai/codyapi

Send an event

POST/codyapi

Start an isolated agent run. Returns immediately with a runId you can poll.

messagestringrequired

The task or message for the agent.

agentIdstringoptional

Target a specific agent. Omit to use your default agent.

namestringoptional

A label for the run (shown in your event log).

deliverbooleanoptional

If true, the agent also delivers its reply to its channel. Default false.

timeoutSecondsnumberoptional

Max seconds the run may take before timing out.

parentRunIdstringoptional

Attach this run as a child of another active or recorded run.

curl -X POST "https://api.agentcody.ai/codyapi" \
  -H "Authorization: Bearer cody_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "n1774177363529",
    "message": "Summarize today's new leads"
  }'

Track delegated runs

A delegated run is a normal run with the optional parentRunId field. Include it when one run starts work on another agent. Execution does not change; Cody only records the relationship so your application can track the complete workflow.

The child returns its own runId plus parentRunId and rootRunId. The parent's status exposes the child in childRunIds. Poll each run independently for its progress and result.

curl -X POST "https://api.agentcody.ai/codyapi" \
  -H "Authorization: Bearer cody_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "research",
    "parentRunId": "parent-run-id",
    "message": "Research the three shortlisted companies."
  }'

List agents

GET/codyapi?action=agents

Retrieve the agents on your instance — use this to discover the agentId values you can target when sending events.

curl "https://api.agentcody.ai/codyapi?action=agents" \
  -H "Authorization: Bearer cody_sk_…"

Run status

GET/codyapi?action=status

Poll a run started by POST /codyapi. Status moves from in_flight to succeeded, failed, cancelled, or unknown. A successful response includes the latest run record, incremental events, and the final assistant text when available.

runIdstringrequired

The runId returned when you sent the event.

cursorintegeroptional

Return only events after this cursor. Start at 0 and retain nextCursor.

Poll every 2–5 seconds. Pass the previous nextCursor as cursor to avoid receiving the same events again. Stop when the run reaches a terminal status.

curl "https://api.agentcody.ai/codyapi?action=status&runId=2cb88653-…&cursor=0" \
  -H "Authorization: Bearer cody_sk_…"

Progress events

Status responses expose a normalized event stream suitable for a live activity UI. Event types are model.changed, agent.thinking, assistant.message, tool.started, and tool.completed.

Tool arguments and outputs are truncated and sensitive values are redacted. The thinking event is only a lifecycle marker: hidden model reasoning is never returned. The stable, user-visible answer is available as result.text.

Steer a run

POST/codyapi

Interrupt or replace the active turn while preserving the public runId and isolated session. Use this when a user changes direction while the agent is working.

actionstringrequired

Set to "steer".

runIdstringrequired

The stable public run identifier.

messagestringrequired

The replacement instruction.

curl -X POST "https://api.agentcody.ai/codyapi" \
  -H "Authorization: Bearer cody_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "steer",
    "runId": "2cb88653-…",
    "message": "Stop researching. Give me the three strongest leads now."
  }'

Cancel a run

POST/codyapi

Request cancellation of an active run. Continue polling until its status is cancelled or another terminal state.

actionstringrequired

Set to "cancel".

runIdstringrequired

The run to cancel.

curl -X POST "https://api.agentcody.ai/codyapi" \
  -H "Authorization: Bearer cody_sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "action": "cancel", "runId": "2cb88653-…" }'

Errors

Errors return a non-2xx status with a JSON body { "ok": false, "error": "…" }.

Status	Meaning
`400`	Bad request — missing fields, invalid cursor, unknown agentId, or unknown parentRunId.
`401`	Missing, malformed, or revoked API key.
`404`	The requested runId is not known by the current gateway process.
`409`	The instance is unavailable, or the run is already in a terminal state.
`502 / 504`	Your instance couldn't be reached or didn't respond in time.

OpenAPI spec

The full API is described by a machine-readable OpenAPI 3.1 spec — the single source of truth for endpoints, parameters, and schemas. Point your API client, code generator, or AI agent at it directly.

{}

/openapi.json

OpenAPI 3.1 spec — import into Postman, Insomnia, or your agent tooling.

Open →

Need a key? Generate one in the dashboard →