API Reference/Endpoints

API Reference

All endpoints are available at https://app.fleetrun.app. Two authentication methods are supported: session cookies (browser) and API key Bearer tokens (programmatic access).

Authentication

Cookie-based (browser / SSR)

Log in via POST /api/auth/login. On success the server sets anfr_session cookie that is included automatically on subsequent requests from the same browser. No extra headers are required.

curl -X POST https://app.fleetrun.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"••••••••"}' \
  -c cookies.txt

# Subsequent requests use the saved cookie
curl https://app.fleetrun.app/api/me -b cookies.txt

API key (programmatic)

Create a key at Settings → API Keys (or via POST /api/keys). Keys have the prefix fr_ and are org-scoped. Pass the key in the Authorization header:

Authorization: Bearer fr_xxxxxxxxxxxxxxxxxxxxxxxx
# List agents using an API key
curl https://app.fleetrun.app/api/agents \
  -H "Authorization: Bearer fr_xxxxxxxxxxxxxxxxxxxxxxxx"

# Create a task
curl -X POST https://app.fleetrun.app/api/tasks \
  -H "Authorization: Bearer fr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Summarise report","input":"...","assignee":"agt_abc123"}'

API keys are only shown once at creation. Store them in a secret manager. Revoke a key at any time via DELETE /api/keys/[id].

Rate Limiting

Rate limits apply to mutating methods (POST, PATCH, PUT, DELETE) only. GET and HEAD requests are not rate-limited. Limits are enforced per authenticated identity (user or API key) within a 60-second sliding window.

Endpoint
Method(s)
Limit
/api/tasks
POST
60 requests / 60 s
/api/agents
POST
20 requests / 60 s
/api/messages
POST
120 requests / 60 s
All other mutating routes
POST / PATCH / DELETE / PUT
100 requests / 60 s

When a limit is exceeded the API returns 429 Too Many Requests with a Retry-After header containing the number of seconds to wait before retrying:

HTTP/2 429
Retry-After: 14
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please slow down.",
    "retryable": true
  }
}

Error Codes

All error responses share this shape:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please slow down.",
    "retryable": true
  }
}

The retryable flag indicates whether repeating the identical request after a delay is likely to succeed.

Code
Retryable
Description
UNAUTHORIZED
no
No valid session cookie or Bearer token was provided.
FORBIDDEN
no
Authenticated but insufficient permissions or plan limit reached.
NOT_FOUND
no
The requested resource does not exist or belongs to another org.
RATE_LIMITED
yes
Too many requests. Check the Retry-After header.
TASK_LIMIT_REACHED
no
Your current plan does not allow more active tasks. Upgrade or wait for tasks to complete.
VALIDATION_ERROR
no
One or more required fields are missing or malformed.
DB_ERROR
yes
Transient database failure. Retry with exponential backoff.

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.
GET
/api/search
Full-text search across agents and tasks.
GET
/api/export/tasks
Export all tasks as a JSON download.
GET
/api/export/agents
Export all agents as a JSON download.
GET
/api/export/audit
Export the full audit log as a JSON download.
GET
/api/keys
List all API keys for the org (secret values are never returned).
POST
/api/keys
Create a new API key.
DELETE
/api/keys/[id]
Revoke an API key by ID.
GET
/api/audit
List audit log entries for the org.
GET
/api/workspaces
List all workspaces (orgs) the authenticated user belongs to.
GET
/api/workspaces/[id]
Get a single workspace by ID.
PATCH
/api/workspaces/[id]
Update workspace settings (name, etc.).
GET
/api/workspaces/[id]/members
List members of a workspace.
GET
/api/health/agents
Health check for all agents — reports which agents are reachable and their last heartbeat.

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

FieldTypeRequiredDescription
namestringyesDisplay name.
rolestringyesSystem prompt / role description.
modelstringyesModel ID (e.g. claude-sonnet-4-5).
providerstringyesProvider key (anthropic | openai | openrouter).
glyphstringyesSingle emoji used as the agent avatar.
managerstringnoAgent ID of this agent's supervisor.
teamstringnoTeam 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

FieldTypeRequiredDescription
statusstringnoFilter by status (pending | running | done | error | waiting).
assigneestringnoFilter by agent ID.

Returns

Array of Task objects, most recent first.

POST/api/tasks

Create a new task.

Request body

FieldTypeRequiredDescription
titlestringyesShort label for the task.
inputstringyesFull prompt / payload sent to the agent.
assigneestringyesAgent ID to assign the task to.
requesterstringnoAgent ID that created the task.
prioritystringnolow | normal | high. Defaults to normal.
epic_idstringnoAssociate 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

FieldTypeRequiredDescription
taskIdstringyesID 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

FieldTypeRequiredDescription
agentstringnoFilter by agent ID (sender or receiver).
typestringnoFilter by message type.
limitnumbernoMax results. Default 100, max 500.

Returns

Array of Message objects.

GET/api/secrets

List secret keys (values are never returned).

Request body

FieldTypeRequiredDescription
scopestringnoorg | agent. Defaults to org.
agentstringnoAgent ID for agent-scoped secrets.

Returns

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

POST/api/secrets

Create or update a secret.

Request body

FieldTypeRequiredDescription
keystringyesSecret key name (uppercase, underscores).
valuestringyesSecret value — encrypted at rest.
scopestringnoorg | agent. Defaults to org.
agentIdstringnoRequired for agent-scoped secrets.

Returns

{ ok: true }

DELETE/api/secrets

Delete a secret by key and scope.

Request body

FieldTypeRequiredDescription
keystringyesSecret key to delete.
scopestringnoorg | 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

FieldTypeRequiredDescription
namestringyesUnique name for this MCP server.
transportstringyesstdio | http.
commandstringnoExecutable for stdio transport.
argsstring[]noArguments for the command.
urlstringnoURL for http transport.
envobjectnoEnvironment 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

FieldTypeRequiredDescription
periodstringnoday | week | month. Defaults to month.
agentstringnoFilter 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.

GET/api/search

Full-text search across agents and tasks.

Request body

FieldTypeRequiredDescription
qstringyesSearch query string.
typestringnoScope: agents | tasks. Omit to search both.

Returns

Array of matching Agent or Task objects tagged with a type field.

GET/api/export/tasks

Export all tasks as a JSON download.

Returns

JSON file attachment containing all task records.

GET/api/export/agents

Export all agents as a JSON download.

Returns

JSON file attachment containing all agent records.

GET/api/export/audit

Export the full audit log as a JSON download.

Returns

JSON file attachment containing all audit log entries.

GET/api/keys

List all API keys for the org (secret values are never returned).

Returns

Array of { id, name, prefix, createdAt, lastUsedAt }.

POST/api/keys

Create a new API key.

Request body

FieldTypeRequiredDescription
namestringyesHuman-readable label for this key.

Returns

{ id, name, key } — the full key is only returned once at creation time.

DELETE/api/keys/[id]

Revoke an API key by ID.

Returns

{ ok: true }

GET/api/audit

List audit log entries for the org.

Request body

FieldTypeRequiredDescription
limitnumbernoMax results. Default 100.
beforestringnoCursor (ISO timestamp) for pagination.

Returns

Array of AuditEntry objects ordered newest first.

GET/api/workspaces

List all workspaces (orgs) the authenticated user belongs to.

Returns

Array of Workspace objects.

GET/api/workspaces/[id]

Get a single workspace by ID.

Returns

Workspace object with members and plan details.

PATCH/api/workspaces/[id]

Update workspace settings (name, etc.).

Returns

Updated Workspace object.

GET/api/workspaces/[id]/members

List members of a workspace.

Returns

Array of WorkspaceMember objects.

GET/api/health/agents

Health check for all agents — reports which agents are reachable and their last heartbeat.

Returns

Array of { agentId, status, lastSeen }.

Webhooks Planned

Webhook support is on the roadmap. Once available, you will be able to register an HTTPS endpoint that receives a POST with a signed JSON payload whenever one of the following events fires:

Event
Triggered when
task.completed
A task finishes successfully.
task.failed
A task errors out or is cancelled.
agent.error
An agent encounters an unrecoverable error during execution.

All webhook payloads will include a signature in the X-FleetRun-Signature header for verification.

HTTP status codes

Status
Meaning
400
Bad request — missing or invalid fields.
401
Unauthorized — missing or invalid session / Bearer token.
403
Forbidden — plan limit reached or insufficient permissions.
404
Resource not found.
429
Rate limit exceeded — check Retry-After and back off.
500
Internal server error — something went wrong on our end.