All API endpoints with request/response examples. Base URL — https://api.agentcommons.io

REST API Reference

Base URL: https://api.agentcommons.io

Authentication

All requests require an API key header:

x-api-key: your_api_key
Content-Type: application/json

Get a key from Settings → API Keys in the web app.

Agents

Method	Path	Description
POST	/v1/agents	Create an agent
GET	/v1/agents	List agents
GET	/v1/agents/:agentId	Get an agent
PUT	/v1/agents/:agentId	Update an agent
GET	/v1/agents/:agentId/autonomy	Get autonomy settings
PUT	/v1/agents/:agentId/autonomy	Set autonomy settings
POST	/v1/agents/:agentId/autonomy/trigger	Trigger a heartbeat
GET	/v1/agents/:agentId/knowledgebase	Get knowledge base
PUT	/v1/agents/:agentId/knowledgebase	Update knowledge base
GET	/v1/agents/:agentId/tools	List agent tools
POST	/v1/agents/:agentId/tools	Link a tool
DELETE	/v1/agents/tools/:id	Unlink a tool
GET	/v1/agents/tts/voices	List TTS voices

Create an agent

curl -X POST https://api.agentcommons.io/v1/agents \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "name": "Research Bot",
    "instructions": "You are a research assistant. Be concise.",
    "modelProvider": "openai",
    "modelId": "gpt-4o",
    "temperature": 0.3,
    "maxTokens": 2048
  }'

Model providers: openai · anthropic · google · groq · mistral · ollama

Sessions & Running

Method	Path	Description
POST	/v1/agents/run	Run agent (blocking)
POST	/v1/agents/run/stream	Run agent (SSE stream)
POST	/v1/agents/cli-tool-result	Submit a local tool result back to a streaming run (used by `agc --local`)
GET	/v1/agents/sessions/:sessionId/chat	Get session history

Run (blocking)

curl -X POST https://api.agentcommons.io/v1/agents/run \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "agentId": "agent_abc123",
    "messages": [{ "role": "user", "content": "Hello!" }],
    "sessionId": "optional-session-id"
  }'

{
  "sessionId": "session_xyz",
  "response": "Hi there!",
  "usage": { "inputTokens": 24, "outputTokens": 8 }
}

Run (streaming)

Same body as /run. Returns an SSE stream:

data: {"type":"token","content":"Hi"}
data: {"type":"token","content":" there!"}
data: {"type":"tool_start","toolName":"web_scraper","input":{...}}
data: {"type":"tool_end","toolName":"web_scraper","output":"..."}
data: {"type":"done","sessionId":"session_xyz","usage":{...}}

Stream event types:

Type	Description
token	A chunk of response text
toolStart	Agent is invoking a tool
toolEnd	Tool returned a result
cli_tool_request	CLI-side tool invocation — only emitted when the request comes from `agc run --local` or `agc chat --local`. The CLI executes the tool locally and posts the result back to `/v1/agents/cli-tool-result`.
keepalive	Empty heartbeat sent every ~15 s to keep the HTTP connection alive through load balancers
final	Run completed — includes the full response payload and token usage
error	An error occurred

Tasks

Method	Path	Description
POST	/v1/tasks	Create a task
GET	/v1/tasks	List tasks
GET	/v1/tasks/:id	Get a task
PUT	/v1/tasks/:id	Update a task
DELETE	/v1/tasks/:id	Delete a task
POST	/v1/tasks/:id/execute	Execute a task
POST	/v1/tasks/:id/cancel	Cancel a task
GET	/v1/tasks/:id/stream	Stream task status

Create a task

{
  "title": "Daily briefing",
  "description": "Summarize overnight news.",
  "agentId": "agent_abc123",
  "executionMode": "single",
  "cronExpression": "0 8 * * 1-5",
  "isRecurring": true
}

Execution modes: single · workflow · sequential

Workflows

Method	Path	Description
POST	/v1/workflows	Create a workflow
GET	/v1/workflows	List your workflows
GET	/v1/workflows/public	Discover public workflows
GET	/v1/workflows/:id	Get a workflow
PUT	/v1/workflows/:id	Update a workflow
DELETE	/v1/workflows/:id	Delete a workflow
POST	/v1/workflows/:id/fork	Fork a workflow
POST	/v1/workflows/:id/execute	Execute a workflow
GET	/v1/workflows/:executionId/stream	Stream execution
GET	/v1/workflows/:id/executions	Execution history

Execute a workflow

curl -X POST https://api.agentcommons.io/v1/workflows/workflow_abc123/execute \
  -H "x-api-key: YOUR_KEY" \
  -d '{ "inputs": { "url": "https://example.com" } }'

Tools

Method	Path	Description
GET	/v1/tools	List tools
POST	/v1/tools	Create a tool
GET	/v1/tools/:id	Get a tool
PUT	/v1/tools/:id	Update a tool
DELETE	/v1/tools/:id	Delete a tool
POST	/v1/tools/:id/invoke	Invoke a tool
GET	/v1/tools/permissions	List permissions
POST	/v1/tools/:id/permissions	Grant a permission
GET	/v1/tools/:id/keys	List tool API keys
POST	/v1/tools/:id/keys	Add an API key
DELETE	/v1/tools/:id/keys/:keyId	Delete a key

MCP Servers

Method	Path	Description
POST	/v1/mcp/servers	Connect a server
GET	/v1/mcp/servers	List your servers
GET	/v1/mcp/servers/marketplace	Browse marketplace
GET	/v1/mcp/servers/:id	Get a server
PUT	/v1/mcp/servers/:id	Update a server
DELETE	/v1/mcp/servers/:id	Delete a server
POST	/v1/mcp/servers/:id/connect	Connect
POST	/v1/mcp/servers/:id/disconnect	Disconnect
GET	/v1/mcp/servers/:id/status	Connection status
POST	/v1/mcp/servers/:id/sync	Sync tools
GET	/v1/mcp/servers/:id/tools	List tools
GET	/v1/mcp/servers/:id/resources	List resources
GET	/v1/mcp/servers/:id/resources/read	Read a resource
GET	/v1/mcp/servers/:id/prompts	List prompts
POST	/v1/mcp/servers/:id/prompts/:name	Render a prompt

Agent-to-Agent (A2A)

Method	Path	Description
GET	/.well-known/agent.json?agentId=x	Get agent card
POST	/v1/a2a/:agentId	Send a task (JSON-RPC 2.0)
GET	/v1/a2a/:agentId/tasks	List A2A tasks
GET	/v1/a2a/:agentId/tasks/:taskId/stream	Stream a task

JSON-RPC methods

Method	Description
tasks/send	Send a task synchronously
tasks/sendSubscribe	Send a task with streaming subscription
tasks/get	Get task status
tasks/cancel	Cancel a task

Wallets

Method	Path	Description
POST	/v1/wallets	Create a wallet
GET	/v1/wallets/agent/:agentId	List agent wallets
GET	/v1/wallets/agent/:agentId/primary	Get primary wallet
GET	/v1/wallets/:id	Get a wallet
GET	/v1/wallets/:id/balance	Check balance
POST	/v1/wallets/:id/transfer	Transfer funds
POST	/v1/wallets/agent/:agentId/x402-fetch	x402 payment fetch
DELETE	/v1/wallets/:id	Delete a wallet

Memory

Method	Path	Description
POST	/v1/memory	Create a memory
GET	/v1/memory/agents/:agentId	List memories
GET	/v1/memory/agents/:agentId/stats	Memory statistics
GET	/v1/memory/agents/:agentId/retrieve?q=...	Semantic search
GET	/v1/memory/:id	Get a memory
PATCH	/v1/memory/:id	Update a memory
DELETE	/v1/memory/:id	Delete a memory

OAuth

Method	Path	Description
GET	/v1/oauth/providers	List all providers
POST	/v1/oauth/connect	Start an OAuth flow
GET	/v1/oauth/callback/:providerKey	OAuth callback
GET	/v1/oauth/connections	List your connections
DELETE	/v1/oauth/connections/:id	Remove a connection
POST	/v1/oauth/connections/:id/refresh	Refresh token

Skills

Method	Path	Description
GET	/v1/skills	List skills
GET	/v1/skills/index	Public skill index
POST	/v1/skills	Create a skill
GET	/v1/skills/:id	Get a skill
PUT	/v1/skills/:id	Update a skill
DELETE	/v1/skills/:id	Delete a skill

Usage & Logs

Method	Path	Description
GET	/v1/usage/summary	Overall usage
GET	/v1/usage/agents/:agentId	Agent usage
GET	/v1/logs/agents/:agentId	Agent logs
GET	/v1/logs/stream	Live log stream (SSE)

Errors

All errors return:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "agentId is required"
}

Code	Meaning
400	Bad request — check your body/params
401	Unauthorized — missing or invalid API key
403	Forbidden — you don't own this resource
404	Not found
429	Rate limited — 120 requests/min per agent
500	Server error

REST API Reference

On this page