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