API Reference

Cody API

Send events to your Cody agents programmatically and poll their results — over a simple HTTPS API.

Base URLhttps://api.heycody.ink/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 — the same isolated-run engine the dashboard uses, exposed over HTTP.

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.heycody.ink/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.

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

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.heycody.ink/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, or unknown.

runIdstringrequired

The runId returned when you sent the event.

curl "https://api.heycody.ink/codyapi?action=status&runId=2cb88653-…" \
  -H "Authorization: Bearer cody_sk_…"

Errors

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

Status	Meaning
`400`	Bad request — missing message, or an unknown agentId.
`401`	Missing, malformed, or revoked API key.
`409`	Your Cody instance isn't provisioned or is still starting.
`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 →