Already using the Anthropic or OpenAI SDK? Ship your agent to production in one call.

See the quickstart

Agents API

Spawn, list, get, and stop agents via the public API.

The agents API is the spawn primitive — one call to create an agent, plus read paths to monitor it.

Spawn an agent

POST/api/v1/agents

Create and start a new agent. Returns immediately with status=spawning.

Request body

| Field | Type | Description | | --- | --- | --- | | task (required) | string | The natural-language task prompt. Up to 4,000 characters. The Mind reads this as the user message. | | name | string | Optional display name shown in the Console. Defaults to an auto-generated title summarizing the task. | | region | string | Container region (default: iad). Only iad today; multi-region ships soon. |

Response

json
{
  "agent_id": "ag_8cGoiD4ujxjGOrnjC0QsV",
  "name": "Untitled Agent",
  "status": "spawning",
  "task": "...",
  "created_at": "2026-05-14T18:42:00.000Z",
  "model": "jettson-6.0",
  "container": { "region": "iad", "status": "starting" }
}

Example

bash
curl -X POST https://jettson.dev/api/v1/agents \
  -H "Authorization: Bearer $JETTSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Browse https://news.ycombinator.com, return the top 5 story titles as JSON.",
    "name": "HN Top 5"
  }'

Errors

| Code | When | | --- | --- | | invalid_task | Missing or too-long task | | concurrent_limit_reached | Active agents at plan cap | | monthly_quota_exceeded | Agent-hours budget used for the month | | rate_limited | Spawned too many times this minute/hour |

List agents

GET/api/v1/agents

Returns the caller's agents, newest first. Paginated via opaque cursors.

Query

| Field | Type | Description | | --- | --- | --- | | limit | number | How many to return (default 20, max 100). | | cursor | string | Pass the next_cursor from a previous response to fetch the next page. |

Response

json
{
  "data": [
    {
      "agent_id": "ag_...",
      "name": "...",
      "status": "completed",
      "task": "...",
      "created_at": "...",
      "updated_at": "...",
      "final_result": "...",
      "progress": [...],
      "error": null,
      "model": "jettson-6.0"
    }
  ],
  "next_cursor": "ag_xxxx"
}

next_cursor is null when there are no more pages.

Get one agent

GET/api/v1/agents/{id}

Returns full agent state including progress events.

Response

json
{
  "agent_id": "ag_...",
  "name": "...",
  "status": "running",
  "task": "...",
  "created_at": "...",
  "updated_at": "...",
  "final_result": null,
  "progress": [
    { "ts": 1715712000000, "kind": "info", "message": "Planning task…" },
    { "ts": 1715712001500, "kind": "tool_use", "message": "jettson_browser_navigate(…)" }
  ],
  "error": null,
  "model": "jettson-6.0"
}

Poll this endpoint to watch a long-running agent, or use the Console's live view (it subscribes to live updates).

Errors

| Code | When | | --- | --- | | agent_not_found | Wrong ID, or the ID belongs to a different account |

Stop an agent

DELETE/api/v1/agents/{id}

Cancel a running agent. Idempotent — terminal agents return 200 unchanged.

Response

json
{ "agent_id": "ag_...", "status": "stopped" }

The container receives SIGTERM, gets ~10 seconds to clean up, then is destroyed. final_result won't be populated.

Logs subcollection

The full event stream (every thinking, tool_use, tool_result, and terminal event) lives at:

text
GET /api/v1/agents/{id}/logs

This is read-only and paginated. Most consumers prefer the Console's live view for the same data.

Related