API Reference

AgentFlow exposes a comprehensive REST API with SSE streaming support. All endpoints require Bearer token authentication unless noted otherwise.

Base URL

https://your-instance.agentflow.ai

Authentication

Include your AgentFlow-issued bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-instance.agentflow.ai/api/v1/agents

Interactive documentation

Interactive API documentation is available on every AgentFlow deployment:

Format	URL	Description
Swagger UI	`/docs`	Interactive API explorer with try-it-out
ReDoc	`/redoc`	Clean, readable API reference
OpenAPI spec	`/openapi.json`	Machine-readable spec for code generation

Endpoint groups

System

Method	Path	Description
`GET`	`/`	Health check (API status)
`GET`	`/health`	Detailed health check (API + memory)
`GET`	`/ready`	Readiness probe (verifies database)
`GET`	`/api/v1/agents/stats`	Agent registry statistics
`GET`	`/api/v1/models`	List available LLM models with capabilities and pricing

Usage and budgets

These routes require an authenticated human admin principal. Configure accepted scopes with AGENTFLOW_ADMIN_SCOPES.

Method	Path	Description
`GET`	`/api/v1/admin/usage/summary?range=7d`	Aggregate tenant usage for `7d`, `30d`, `90d`, or `all`
`GET`	`/api/v1/admin/budget`	Get tenant monthly LLM budget override, effective cap, and reset timestamp
`PUT`	`/api/v1/admin/budget`	Set or clear the tenant monthly LLM budget override
`GET`	`/api/v1/admin/budget/users`	Get per-user monthly budget caps and current-month spend
`PUT`	`/api/v1/admin/budget/users`	Set or clear a user’s monthly budget override

Agents

Method	Path	Description
`GET`	`/api/v1/agents`	List all agents
`GET`	`/api/v1/agent/{id}`	Get agent details
`GET`	`/api/v1/agent/{id}/config`	Get agent configuration
`PATCH`	`/api/v1/agent/{id}/config`	Update agent configuration
`DELETE`	`/api/v1/agent/{id}`	Delete an agent

Agent discovery uses the plural /api/v1/agents route. Agent-specific management and execution routes keep the singular /api/v1/agent/{id} prefix.

Agent execution

Method	Path	Description
`POST`	`/api/v1/agent/{id}/chat`	Chat with an agent (streaming or non-streaming)
`POST`	`/api/v1/agent/{id}/tools/{tool}/run`	Execute a specific tool
`POST`	`/api/v1/agent/{id}/subagents/{sub_id}/run`	Run a sub-agent directly
`POST`	`/api/v1/agent/{id}/context/preload`	Preload cacheable context blocks for one agent

Sub-agents

Method	Path	Description
`GET`	`/api/v1/agent/{id}/subagents`	List sub-agents
`POST`	`/api/v1/agent/{id}/subagents`	Create a sub-agent
`GET`	`/api/v1/agent/{id}/subagents/{sub_id}`	Get sub-agent details
`GET`	`/api/v1/agent/{id}/subagents/{sub_id}/config`	Get sub-agent configuration
`PATCH`	`/api/v1/agent/{id}/subagents/{sub_id}`	Update sub-agent
`DELETE`	`/api/v1/agent/{id}/subagents/{sub_id}`	Delete sub-agent
`GET`	`/api/v1/agent/{id}/subagents/{sub_id}/tools`	List sub-agent tools
`POST`	`/api/v1/agent/{id}/subagents/{sub_id}/tools`	Assign tool to sub-agent
`DELETE`	`/api/v1/agent/{id}/subagents/{sub_id}/tools/{tool}`	Remove tool from sub-agent
`GET`	`/api/v1/agent/{id}/subagents/{sub_id}/available-tools`	List available tools for assignment

Tools

Method	Path	Description
`GET`	`/api/v1/agent/{id}/tools`	List agent tools
`GET`	`/api/v1/agent/{id}/tools/{tool}`	Get tool details
`POST`	`/api/v1/agent/{id}/tools`	Register a new tool
`PATCH`	`/api/v1/agent/{id}/tools/{tool}`	Update a persisted tool
`POST`	`/api/v1/agent/{id}/tools/generate`	Generate tool code from description
`POST`	`/api/v1/agent/{id}/tools/dry-run`	Test tool execution in sandbox
`POST`	`/api/v1/agent/{id}/tools/persist`	Save generated tool permanently
`PUT`	`/api/v1/agent/{id}/tools/{tool}/approval`	Configure tool approval
`DELETE`	`/api/v1/agent/{id}/tools/{tool}`	Remove a tool

Capabilities

Method	Path	Description
`POST`	`/api/v1/agent/{id}/capability/retrieve`	Invoke retrieval capability
`POST`	`/api/v1/agent/{id}/capability/plan`	Invoke planning capability
`POST`	`/api/v1/agent/{id}/capability/reflect`	Invoke reflection capability

Prompt blocks

Method	Path	Description
`GET`	`/api/v1/prompt-blocks`	List registered static and local dynamic prompt blocks
`POST`	`/api/v1/prompt-blocks`	Create a DB-backed static prompt block
`GET`	`/api/v1/prompt-blocks/{name}`	Get prompt block metadata and static body when available
`PATCH`	`/api/v1/prompt-blocks/{name}`	Update static body or dynamic metadata overrides
`DELETE`	`/api/v1/prompt-blocks/{name}`	Delete DB-backed static blocks or dynamic metadata overrides
`POST`	`/api/v1/prompt-blocks/{name}/preview`	Preview one wrapped prompt block
`POST`	`/api/v1/prompt-blocks/{name}/invalidate-cache`	Clear cached output for a dynamic block

Context blocks

Method	Path	Description
`GET`	`/api/v1/agent/{id}/context/blocks`	List registered context blocks for an agent
`POST`	`/api/v1/agent/{id}/context/blocks/build`	Build and return rendered context block content
`POST`	`/api/v1/agent/{id}/context/preload`	Preload cacheable context blocks for one agent

Skills

Method	Path	Description
`GET`	`/api/v1/skills`	List all discovered skills
`GET`	`/api/v1/skills/{name}`	Get skill by name (includes full playbook body)
`GET`	`/api/v1/skills/{name}/content`	Get skill content or support file
`GET`	`/api/v1/agent/{id}/skills`	List skills assigned to a specific agent

Knowledge bases

Method	Path	Description
`GET`	`/api/v1/knowledge-bases`	List all knowledge bases
`GET`	`/api/v1/knowledge-bases/{id}`	Get KB details
`POST`	`/api/v1/knowledge-bases/create-from-url`	Create KB from URL
`POST`	`/api/v1/knowledge-bases`	Create KB from uploaded files
`POST`	`/api/v1/knowledge-bases/search`	Search across multiple knowledge bases
`POST`	`/api/v1/knowledge-bases/{id}/search`	Search a knowledge base
`POST`	`/api/v1/knowledge-bases/{id}/documents`	Add documents to KB
`POST`	`/api/v1/knowledge-bases/{id}/documents/filter`	Filter documents by metadata
`GET`	`/api/v1/knowledge-bases/{id}/files`	List files in KB
`GET`	`/api/v1/knowledge-bases/{id}/documents`	List documents (chunks)
`GET`	`/api/v1/knowledge-bases/{id}/summary`	Get KB summary
`GET`	`/api/v1/knowledge-bases/{id}/metadata-schema`	Get KB metadata schema
`GET`	`/api/v1/knowledge-bases/{id}/content`	Browse KB content
`GET`	`/api/v1/knowledge-bases/{id}/chunks/{chunk_id}`	Get chunk details
`GET`	`/api/v1/knowledge-bases/search-defaults`	Get search parameter defaults
`PUT`	`/api/v1/knowledge-bases/{id}`	Update KB metadata
`POST`	`/api/v1/knowledge-bases/{id}/refresh`	Re-index KB
`POST`	`/api/v1/knowledge-bases/{id}/documents/{doc_id}/refresh`	Refresh a specific document
`POST`	`/api/v1/knowledge-bases/preview`	Preview chunking (SSE supported)
`DELETE`	`/api/v1/knowledge-bases/{id}`	Delete KB
`DELETE`	`/api/v1/knowledge-bases/{id}/documents/{doc_id}`	Delete document

Agent-scoped knowledge bases

Method	Path	Description
`GET`	`/api/v1/agents/{id}/knowledge-bases`	List KBs bound to agent
`POST`	`/api/v1/agents/{id}/knowledge-bases/{kb_id}`	Bind KB to agent
`DELETE`	`/api/v1/agents/{id}/knowledge-bases/{kb_id}`	Unbind KB from agent
`POST`	`/api/v1/agents/{id}/knowledge-bases/{kb_id}/search`	Search KB through agent

Documents

Method	Path	Description
`GET`	`/api/v1/documents/viewer`	Fetch parsed text for an attachment or KB document

Conversations

Method	Path	Description
`POST`	`/api/v1/conversations`	Create a conversation
`GET`	`/api/v1/conversations`	List conversations
`GET`	`/api/v1/conversations/search`	Search conversation titles and chat history
`GET`	`/api/v1/conversations/{id}`	Get conversation metadata
`GET`	`/api/v1/conversations/{id}/messages`	List flat chat messages
`POST`	`/api/v1/conversations/{id}/messages`	Add a user message
`GET`	`/api/v1/conversations/{id}/cached-results/{cache_id}`	Retrieve a cached tool result payload
`GET`	`/api/v1/conversations/{id}/cached-results/{cache_id}/items`	Retrieve cached tool result items
`GET`	`/api/v1/conversations/{id}/timeline`	Get UI-ready conversation timeline
`GET`	`/api/v1/conversations/{id}/stream`	Stream durable conversation snapshots
`GET`	`/api/v1/conversations/{id}/runs`	List execution runs
`GET`	`/api/v1/conversations/{id}/markers`	List conversation markers
`GET`	`/api/v1/conversations/{id}/llm-format`	Export in LLM format
`PUT`	`/api/v1/conversations/{id}`	Update conversation metadata
`DELETE`	`/api/v1/conversations/{id}`	Delete conversation
`GET`	`/api/v1/agent/conversations/{id}/title`	Get conversation title
`PUT`	`/api/v1/agent/conversations/{id}/title`	Update title
`POST`	`/api/v1/agent/conversations/{id}/title/generate`	Generate title from content
`POST`	`/api/v1/agent/{id}/conversations/{conv_id}/compress`	Compact chat history

Approvals

Method	Path	Description
`GET`	`/api/v1/approvals/pending`	List pending approvals
`GET`	`/api/v1/approvals/{id}`	Get approval details
`POST`	`/api/v1/approvals/{id}/respond`	Approve, deny, or approve with modified arguments
`DELETE`	`/api/v1/approvals/{id}`	Cancel approval
`POST`	`/api/v1/approvals/bulk-respond`	Bulk approve/deny
`GET`	`/api/v1/approvals/tools/{tool_id}/stats`	Tool approval statistics
`GET`	`/api/v1/approvals/dashboard/summary`	Dashboard summary
`POST`	`/api/v1/approvals/cleanup-expired`	Clean up expired requests

Questions

Method	Path	Description
`POST`	`/api/v1/questions/{question_id}/respond`	Respond to an agent question

Artifacts

Method	Path	Description
`GET`	`/api/v1/artifacts/types`	List registered artifact types with UI metadata
`GET`	`/api/v1/artifacts/{artifact_id}`	Get artifact content and state
`GET`	`/api/v1/artifacts/conversation/{conversation_id}`	List artifacts in a conversation
`PATCH`	`/api/v1/artifacts/{artifact_id}/state`	Update artifact state (sent, scheduled, etc.)
`PATCH`	`/api/v1/artifacts/{artifact_id}/content`	Edit artifact content inline
`POST`	`/api/v1/artifacts/{artifact_id}/create-task`	Create a task from a draft artifact
`POST`	`/api/v1/artifacts/{artifact_id}/schedule-meeting`	Schedule meeting via Google Calendar
`POST`	`/api/v1/artifacts/{artifact_id}/scheduled-task`	Create/update scheduled agent task
`POST`	`/api/v1/artifacts/{artifact_id}/scheduled-task/active`	Toggle scheduled task active/inactive
`DELETE`	`/api/v1/artifacts/{artifact_id}/scheduled-task`	Delete scheduled task
`POST`	`/api/v1/artifacts/{artifact_id}/interaction`	Record user interaction with artifact
`GET`	`/api/v1/artifacts/{artifact_id}/download`	Download artifact as DOCX

Cancellation

Method	Path	Description
`GET`	`/api/v1/cancel/active-calls`	List active executions
`POST`	`/api/v1/cancel/{call_id}`	Cancel specific execution
`POST`	`/api/v1/cancel/all`	Cancel all executions
`POST`	`/api/v1/cancel/background-task/{task_id}`	Cancel a background task

LLM

Method	Path	Description
`POST`	`/api/v1/llm/chat`	Direct LLM chat (SSE supported)
`POST`	`/api/v1/llm/autocomplete`	Text autocomplete
`POST`	`/api/v1/llm/recommend`	Content recommendations
`GET`	`/api/v1/llm/config`	Get tenant LLM mode, provider configs, allowlist, and default map
`POST`	`/api/v1/llm/config`	Save one encrypted BYO provider key and model policy
`PUT`	`/api/v1/llm/config/mode`	Switch tenant between platform and BYO keys
`GET`	`/api/v1/llm/config/model-options`	List models and backend use cases admins can map
`POST`	`/api/v1/llm/config/test-key`	Validate a provider key without storing it
`DELETE`	`/api/v1/llm/config/{config_uuid}`	Delete one BYO provider configuration

Email

Method	Path	Description
`POST`	`/api/v1/emails/draft`	Draft an email
`POST`	`/api/v1/emails/draft-reply`	Draft a reply email
`POST`	`/api/v1/emails/draft-email`	Draft a new email
`POST`	`/api/v1/emails/send`	Send an email
`POST`	`/api/v1/emails/query`	Search emails

Meetings

Method	Path	Description
`POST`	`/api/v1/meetings/summarize-transcript`	Summarize a meeting transcript

Tasks

Method	Path	Description
`GET`	`/api/v1/tasks`	List tasks
`POST`	`/api/v1/tasks`	Create a task
`GET`	`/api/v1/tasks/{uuid}`	Get task details
`PATCH`	`/api/v1/tasks/{uuid}`	Update a task
`POST`	`/api/v1/tasks/{uuid}/toggle`	Toggle task active/inactive
`DELETE`	`/api/v1/tasks/{uuid}`	Delete a task

Activity timeline

Method	Path	Description
`POST`	`/api/v1/activity/timeline`	Cross-domain communication timeline for accounts/contacts

Files & attachments

Method	Path	Description
`POST`	`/api/v1/attachments`	Upload an attachment
`GET`	`/api/v1/attachments`	List attachments
`GET`	`/api/v1/attachments/{file_id}`	Get attachment metadata
`GET`	`/api/v1/attachments/{file_id}/content`	Get attachment content
`GET`	`/api/v1/attachments/{file_id}/download`	Download attachment
`DELETE`	`/api/v1/attachments/{file_id}`	Delete an attachment
`POST`	`/api/v1/s3/upload`	Upload file to S3
`POST`	`/api/v1/files`	Upload file for batch processing (CSV/JSON, up to 100MB)

Completions (sync)

Method	Path	Description
`POST`	`/api/v1/completions/run`	Run batch operation (up to 50 items)
`POST`	`/api/v1/completions/label`	Classify items against categories
`POST`	`/api/v1/completions/extract`	Extract structured data
`POST`	`/api/v1/completions/summarize`	Summarize content
`POST`	`/api/v1/completions/enrich`	Enrich data with computed fields
`POST`	`/api/v1/completions/chat`	Direct LLM chat
`POST`	`/api/v1/completions/recommend`	Content recommendations
`POST`	`/api/v1/completions/autocomplete`	Text autocomplete

Batches (async)

Method	Path	Description
`POST`	`/api/v1/batches`	Submit async batch job
`GET`	`/api/v1/batches/{batch_id}`	Get batch status and progress
`GET`	`/api/v1/batches/{batch_id}/output`	Read paginated output as JSON, JSONL, or CSV
`POST`	`/api/v1/batches/{batch_id}/cancel`	Cancel a running batch

User settings & personalization

Method	Path	Description
`GET`	`/api/v1/settings`	Get merged user settings
`PATCH`	`/api/v1/settings`	Update user settings (deep merge)
`POST`	`/api/v1/settings/reset`	Reset to platform defaults
`GET`	`/api/v1/settings/defaults`	Get platform default settings

Memory

Method	Path	Description
`GET`	`/api/v1/memory/blocks`	List all memory blocks
`GET`	`/api/v1/memory/blocks/{type}`	Get a specific memory block
`PUT`	`/api/v1/memory/blocks/{type}`	Compare-and-set update a memory block
`DELETE`	`/api/v1/memory/blocks/{type}`	Delete a memory block
`POST`	`/api/v1/memory/recall`	Search archival memory

Voice (Vapi)

Method	Path	Description
`POST`	`/api/vapi/webhook`	Vapi webhook receiver (status, transcripts, end-of-call reports)
`GET`	`/api/calls/lookup/by-phone`	Look up active call by phone number
`GET`	`/api/calls/{vapi_call_id}`	Get live call state

​API Reference

​Base URL

​Authentication

​Interactive documentation

​Endpoint groups

​System

​Usage and budgets

​Agents

​Agent execution

​Sub-agents

​Tools

​Capabilities

​Prompt blocks

​Context blocks

​Skills

​Knowledge bases

​Agent-scoped knowledge bases

​Documents

​Conversations

​Approvals

​Questions

​Artifacts

​Cancellation

​LLM

​Email

​Meetings

​Tasks

​Activity timeline

​Files & attachments

​Completions (sync)

​Batches (async)

​User settings & personalization

​Memory

​Voice (Vapi)