API Reference

Complete reference for the AgentBackend REST API. All endpoints are listed below, grouped by domain.

Base URL

https://api.agentbackend.ai

Authentication

All requests require an Authorization header with either an API key (Bearer ak_...) or a JWT token (Bearer eyJ...).

Exceptions: GET /health and GET /v1/status are public.

System

MethodEndpointDescription
GET/healthHealth check (public)
GET/v1/statusPlatform status (public)
GET/llms.txtLLM-readable summary (public)
GET/llms-full.txtFull LLM-readable API reference (public)

Agents

MethodEndpointDescription
POST/v1/agentsCreate agent
GET/v1/agentsList agents (paginated)
GET/v1/agents/:idGet agent
PUT/v1/agents/:idUpdate agent
DELETE/v1/agents/:idDelete agent
GET/v1/agents/presetsList presets
POST/v1/agents/generateGenerate config from prompt
POST/v1/agents/generate/streamGenerate config (streaming)
GET/v1/agents/:id/exportExport config
POST/v1/agents/importImport config
POST/v1/agents/:id/testRun behavior tests
POST/v1/agents/:id/auditSecurity audit

Run

MethodEndpointDescription
POST/v1/runRun agent
POST/v1/run/streamRun agent (streaming SSE)
POST/v1/run/with-filesRun with file attachments
POST/v1/run/:run_id/cancelCancel run

Versions

MethodEndpointDescription
GET/v1/agents/:id/versionsVersion history
GET/v1/agents/:id/versions/:versionVersion detail
GET/v1/agents/:id/versions/compareCompare versions
POST/v1/agents/:id/rollbackRollback to version

Knowledge

MethodEndpointDescription
POST/v1/knowledge/uploadUpload document
POST/v1/knowledge/urlIngest from URL
GET/v1/knowledgeList documents
GET/v1/knowledge/:id/statusDocument status
DELETE/v1/knowledge/:idDelete document
POST/v1/agents/:id/knowledge/:doc_idAttach to agent
DELETE/v1/agents/:id/knowledge/:doc_idDetach from agent

Sessions

MethodEndpointDescription
GET/v1/sessionsList sessions
GET/v1/sessions/:id/messagesGet messages
DELETE/v1/sessions/:idDelete session
POST/v1/sessions/:id/checkpointCreate checkpoint
POST/v1/sessions/:id/rewindRewind to checkpoint
POST/v1/sessions/:id/forkFork session

Data Store

MethodEndpointDescription
GET/v1/tenant/statusGet schema status, table list, and migration count
GET/v1/tenant/migrationsList all DDL migration versions with status
POST/v1/tenant/rollbackRollback a specific migration version

Channels

MethodEndpointDescription
POST/v1/channels/:type/botsRegister bot
GET/v1/channels/botsList bots
GET/v1/channels/bots/:idGet bot
PATCH/v1/channels/bots/:idUpdate bot
DELETE/v1/channels/bots/:idDelete bot
POST/v1/agents/:id/channelsLink agent to bot
GET/v1/agents/:id/channelsList agent channels
DELETE/v1/agents/:id/channels/:bot_idUnlink agent

Schedules

MethodEndpointDescription
POST/v1/schedulesCreate task
GET/v1/schedulesList tasks
GET/v1/schedules/:idGet task
PUT/v1/schedules/:idUpdate task
DELETE/v1/schedules/:idDelete task
PATCH/v1/schedules/:id/pausePause
PATCH/v1/schedules/:id/resumeResume
GET/v1/schedules/:id/runsRun history

Billing

MethodEndpointDescription
POST/v1/billing/checkoutCreate checkout
POST/v1/billing/portalCustomer portal
GET/v1/billing/statusBilling status

Account

MethodEndpointDescription
POST/v1/keysCreate API key with optional spending limit (JWT only)
GET/v1/keysList keys (includes spend data)
PATCH/v1/keys/:idUpdate key spending limit
DELETE/v1/keys/:idRevoke key
DELETE/v1/accountDelete account
GET/v1/account/preferencesGet preferences
PUT/v1/account/preferencesUpdate preferences

Observability

MethodEndpointDescription
GET/v1/observability/summaryMetrics summary
GET/v1/observability/pipelinePipeline analytics
GET/v1/observability/runsRun listing
GET/v1/observability/runs/:idRun detail

Request & Response Examples

POST /v1/run — Request

json
{
  "agent_id": "string (required)",
  "message": "string (required)",
  "session_id": "string (optional) — conversation continuity",
  "context": {"key": "value"},
  "images": ["base64_or_url"],
  "max_cost": 0.05,
  "output_schema": {},
  "dry_run": false,
  "credentials": {"GITHUB_TOKEN": "..."}
}

POST /v1/run — Response

json
{
  "success": true,
  "output": "Agent's response text",
  "citations": [{"source": "...", "content": "..."}],
  "reasoning_content": "Extended thinking (if enabled)",
  "metadata": {
    "cost": 0.003,
    "input_tokens": 150,
    "output_tokens": 80,
    "model": "..."
  }
}

POST /v1/agents — Request (key fields)

json
{
  "name": "string",
  "type": "single | chain | supervisor | society_of_mind | workflow",
  "model": "openai/gpt-4o-mini",
  "instructions": "System prompt",
  "description": "Agent description",
  "tools": [{"name": "web_search", "type": "catalog"}],
  "deployed": true,
  "memory": {"type": "semantic"},
  "guardrails": {"moderation": true, "pii_filter": true},
  "max_turns": 10,
  "planning": false,
  "reasoning": false
}

All endpoints require an Authorization header unless noted otherwise. Exceptions: GET /health, GET /v1/status, and webhook endpoints.

API keys are created via POST /v1/keys and require JWT authentication — you cannot create an API key using another API key.