API Reference

All endpoints are available at https://app.fleetrun.app. Authenticate with a Bearer token from Settings → API Tokens.

Authentication

Include your token in the Authorization header:

Authorization: Bearer fr_live_xxxxxxxxxxxxxxxxxxxx

Tokens are org-scoped. All requests are rate-limited to 120 requests/minute per token.

Endpoints

Method

Path

Description

GET

/api/agents

List all agents in the org.

POST

/api/agents

Create a new agent.

GET

/api/agents/[id]

Get a single agent by ID.

PATCH

/api/agents/[id]

Update agent fields (name, role, model, status, etc.).

DELETE

/api/agents/[id]

Archive an agent (soft delete).

GET

/api/tasks

List tasks. Supports filtering by status and assignee.

POST

/api/tasks

Create a new task.

GET

/api/tasks/[id]

Get a single task by ID.

PATCH

/api/tasks/[id]

Update task fields (status, priority, assignee).

POST

/api/run

Execute a task. Returns a Server-Sent Events stream of execution events.

GET

/api/messages

List messages on the bus. Supports filtering by agent, type, and time range.

GET

/api/secrets

List secret keys (values are never returned).

POST

/api/secrets

Create or update a secret.

DELETE

/api/secrets

Delete a secret by key and scope.

GET

/api/mcps

List all configured MCP servers.

POST

/api/mcps

Add a new MCP server.

GET

/api/usage

Get token usage and task counts for the org, optionally broken down by agent or model.

GET

/api/me

Return the authenticated user and org details.

Detailed reference

GET/api/agents

List all agents in the org.

Returns

Array of Agent objects.

POST/api/agents

Create a new agent.

Request body

Field	Type	Required	Description
`name`	string	yes	Display name.
`role`	string	yes	System prompt / role description.
`model`	string	yes	Model ID (e.g. claude-sonnet-4-5).
`provider`	string	yes	Provider key (anthropic \| openai \| openrouter).
`glyph`	string	yes	Single emoji used as the agent avatar.
`manager`	string	no	Agent ID of this agent's supervisor.
`team`	string	no	Team name to assign the agent to.

Returns

Created Agent object.

GET/api/agents/[id]

Get a single agent by ID.

Returns

Agent object.

PATCH/api/agents/[id]

Update agent fields (name, role, model, status, etc.).

Returns

Updated Agent object.

DELETE/api/agents/[id]

Archive an agent (soft delete).

Returns

{ ok: true }

GET/api/tasks

List tasks. Supports filtering by status and assignee.

Request body

Field	Type	Required	Description
`status`	string	no	Filter by status (pending \| running \| done \| error \| waiting).
`assignee`	string	no	Filter by agent ID.

Returns

Array of Task objects, most recent first.

POST/api/tasks

Create a new task.

Request body

Field	Type	Required	Description
`title`	string	yes	Short label for the task.
`input`	string	yes	Full prompt / payload sent to the agent.
`assignee`	string	yes	Agent ID to assign the task to.
`requester`	string	no	Agent ID that created the task.
`priority`	string	no	low \| normal \| high. Defaults to normal.
`epic_id`	string	no	Associate with an epic.

Returns

Created Task object.

GET/api/tasks/[id]

Get a single task by ID.

Returns

Task object with full log history.

PATCH/api/tasks/[id]

Update task fields (status, priority, assignee).

Returns

Updated Task object.

POST/api/run

Execute a task. Returns a Server-Sent Events stream of execution events.

Request body

Field	Type	Required	Description
`taskId`	string	yes	ID of the task to run.

Returns

SSE stream. Events: { type, text } — types include thinking, tool_call, tool_result, output, error.

GET/api/messages

List messages on the bus. Supports filtering by agent, type, and time range.

Request body

Field	Type	Required	Description
`agent`	string	no	Filter by agent ID (sender or receiver).
`type`	string	no	Filter by message type.
`limit`	number	no	Max results. Default 100, max 500.

Returns

Array of Message objects.

GET/api/secrets

List secret keys (values are never returned).

Request body

Field	Type	Required	Description
`scope`	string	no	org \| agent. Defaults to org.
`agent`	string	no	Agent ID for agent-scoped secrets.

Returns

Array of { key, scope, agentId, updatedAt }.

POST/api/secrets

Create or update a secret.

Request body

Field	Type	Required	Description
`key`	string	yes	Secret key name (uppercase, underscores).
`value`	string	yes	Secret value — encrypted at rest.
`scope`	string	no	org \| agent. Defaults to org.
`agentId`	string	no	Required for agent-scoped secrets.

Returns

{ ok: true }

DELETE/api/secrets

Delete a secret by key and scope.

Request body

Field	Type	Required	Description
`key`	string	yes	Secret key to delete.
`scope`	string	no	org \| agent.

Returns

{ ok: true }

GET/api/mcps

List all configured MCP servers.

Returns

Array of MCP server objects.

POST/api/mcps

Add a new MCP server.

Request body

Field	Type	Required	Description
`name`	string	yes	Unique name for this MCP server.
`transport`	string	yes	stdio \| http.
`command`	string	no	Executable for stdio transport.
`args`	string[]	no	Arguments for the command.
`url`	string	no	URL for http transport.
`env`	object	no	Environment variables (can reference secrets).

Returns

Created MCP server object.

GET/api/usage

Get token usage and task counts for the org, optionally broken down by agent or model.

Request body

Field	Type	Required	Description
`period`	string	no	day \| week \| month. Defaults to month.
`agent`	string	no	Filter to a specific agent.

Returns

Usage summary: { total_tokens, task_count, by_agent, by_model, daily_breakdown }.

GET/api/me

Return the authenticated user and org details.

Returns

User object with org, plan, and feature flags.

Error responses

All errors follow this shape:

{ "error": "Human-readable message" }

Status

Meaning

400

Bad request — missing or invalid fields.

401

Unauthorized — missing or invalid Bearer token.

403

Forbidden — plan limit reached or insufficient permissions.

404

Resource not found.

429

Rate limit exceeded — back off and retry.

500

Internal server error — something went wrong on our end.