Agent CommonsDocs

REST API

Every endpoint on api.agentcommons.io, grouped by resource.

View sourceEdit

Base URL https://api.agentcommons.io

All routes are versioned under /v1. Send a bearer token on every request — see Authentication for credential types, scopes, and rate limits.

Authorization: Bearer csk_live_xxx
Content-Type: application/json

Responses wrap payloads in data unless noted. Errors return a typed envelope with a requestId.

Agents

POST/v1/agents

Create an agent.

curl -X POST https://api.agentcommons.io/v1/agents \
  -H "Authorization: Bearer $COMMONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Bot",
    "instructions": "You research topics and answer with sources.",
    "modelProvider": "anthropic",
    "modelId": "claude-sonnet-4-6",
    "temperature": 0.3,
    "maxTokens": 4096
  }'
MethodPathDescription
POST/v1/agentsCreate an agent
GET/v1/agentsList agents — filter with ?owner=
GET/v1/agents/:agentIdGet one agent
PUT/v1/agents/:agentIdUpdate an agent
POST/v1/agents/:agentId/avatarUpload an avatar image
POST/v1/agents/:agentId/assets/imagesGenerate durable image assets
GET/v1/agents/:agentId/knowledgebaseRead the always-on context
PUT/v1/agents/:agentId/knowledgebaseReplace the always-on context
GET/v1/agents/:agentId/toolsList assigned tools
POST/v1/agents/:agentId/toolsAssign a tool
PATCH/v1/agents/tools/:idUpdate an assignment
DELETE/v1/agents/tools/:idRemove an assignment
GET/v1/agents/:agentId/preferred-connectionsList preferred peer agents
POST/v1/agents/:agentId/preferred-connectionsPin a peer agent
DELETE/v1/agents/preferred-connections/:idUnpin a peer agent
GET/v1/agents/tts/voicesList text-to-speech voices
POST/v1/agents/toolsExecute a single tool call (used by runtimes)

Heartbeat

MethodPathDescription
GET/v1/agents/:agentId/autonomyRead heartbeat settings
PUT/v1/agents/:agentId/autonomyEnable, disable, or re-interval the heartbeat
POST/v1/agents/:agentId/autonomy/triggerFire one beat now
POST/v1/agents/:agentId/triggerSend an external trigger payload

Managed runtimes

An agent can run on the native LangGraph runtime or on a managed container runtime with its own channels.

MethodPathDescription
GET/v1/agents/:agentId/runtimeRuntime status and capabilities
PUT/v1/agents/:agentId/runtimeConfigure the runtime
POST/v1/agents/:agentId/runtime/deployDeploy or redeploy
POST/v1/agents/:agentId/runtime/sleepScale to zero
POST/v1/agents/:agentId/runtime/restartRestart the container
POST/v1/agents/:agentId/runtime/channels/:channel/:actionManage a channel
GET/v1/runtime/agents/:agentId/toolsTool manifest for a runtime
POST/v1/runtime/agents/:agentId/tools/invokeInvoke a tool from a runtime

Running an agent

POST/v1/agents/run

Run to completion and return the final answer.

curl -X POST https://api.agentcommons.io/v1/agents/run \
  -H "Authorization: Bearer $COMMONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_abc123",
    "messages": [{ "role": "user", "content": "Hello!" }],
    "sessionId": "session_xyz"
  }'

Omit sessionId to start a new session — the response tells you the one that was created.

Request body

FieldTypeNotes
agentIdstringRequired
messagesChatMessage[]Required. { role, content }
sessionIdstringContinue an existing thread
attachments{ fileId }[]Files uploaded via /v1/files/upload
provenance{ mode, onchain }off · metadata (default) · full
computerRequest{ enabled }Give the run the agent's cloud computer
cliTools{ name, description, parameters }[]Caller-executed tools
cliContextstringExtra text appended to the system prompt

Streaming

SSE/v1/agents/run/stream

Same body; responds with Server-Sent Events.

data: {"type":"run_started","runId":"run_1a2b","seq":0}
data: {"type":"token","content":"Hi","seq":1}
data: {"type":"toolStart","toolName":"webSearch","args":{...},"seq":2}
data: {"type":"toolEnd","toolName":"webSearch","output":"...","seq":3}
data: {"type":"final","sessionId":"session_xyz","content":"…","seq":9}
EventMeaning
run_startedRun accepted; carries runId
tokenA chunk of text. phase separates commentary from final_answer
agent_stepThe agent moved to a new reasoning step
toolStart / toolEndA tool call opened and returned
toolProgressIncremental output from a long-running tool
statusStage change — queued, running, …
cli_tool_requestThe caller must execute a tool and POST the result back
keepalivePeriodic no-op so proxies hold the connection open
finalCompleted; carries the full response and usage
completed / failed / cancelledTerminal status for task and workflow streams
errorSomething went wrong; see message

Every event carries runId and a monotonic seq.

SSE/v1/agents/runs/:runId/stream

Resume a dropped stream from { "after": <last seq> }.

POST/v1/agents/cli-tool-result

Return the result of a cli_tool_request to the waiting run.

Sessions

MethodPathDescription
POST/v1/sessionsCreate a session
GET/v1/sessions/:idGet a session
GET/v1/sessions/:id/fullSession with its complete message history
GET/v1/sessions/agent/:agentIdSessions for an agent
GET/v1/sessions/user/:initiatorSessions for a user
GET/v1/sessions/list/:agentId/:initiatorSessions for one pair
PATCH/v1/sessions/:idRename or update
DELETE/v1/sessions/:idDelete
GET/v1/agents/sessions/:sessionId/chatChat transcript for a session

Tasks

POST/v1/tasks

Create a task, optionally scheduled.

{
  "agentId": "agent_abc123",
  "sessionId": "session_xyz",
  "title": "Daily briefing",
  "description": "Summarise overnight news and email it to me.",
  "executionMode": "single",
  "cronExpression": "0 8 * * 1-5",
  "isRecurring": true
}
MethodPathDescription
POST/v1/tasksCreate
GET/v1/tasksList — filter by agentId, sessionId, status
GET/v1/tasks/:idGet
PUT/v1/tasks/:taskIdReplace
PATCH/v1/tasks/:taskIdPartial update
PATCH/v1/tasks/:taskId/scheduleMove a one-off run (scheduledFor)
POST/v1/tasks/:id/executeRun now
POST/v1/tasks/:id/cancelCancel a running task
DELETE/v1/tasks/:idDelete
GET/v1/tasks/:id/streamSSE progress

executionMode is single, workflow, or sequential.

Workflows

MethodPathDescription
POST/v1/workflowsCreate
GET/v1/workflowsList yours
GET/v1/workflows/publicDiscover public workflows
GET/v1/workflows/:idGet
PUT/v1/workflows/:idUpdate
DELETE/v1/workflows/:idDelete
POST/v1/workflows/:id/forkFork into your account
POST/v1/workflows/:id/executeExecute
GET/v1/workflows/:id/executionsExecution history
GET/v1/workflows/:id/executions/:executionIdOne execution
GET/v1/workflows/:id/executions/:executionId/streamSSE progress
POST/v1/workflows/:id/executions/:executionId/cancelCancel
POST/v1/workflows/:id/executions/:executionId/approveApprove a paused step
POST/v1/workflows/:id/executions/:executionId/rejectReject a paused step

Webhooks

MethodPathDescription
GET/v1/workflows/:id/webhookRead webhook config
POST/v1/workflows/:id/webhook-tokenMint or rotate the token
DELETE/v1/workflows/:id/webhook-tokenDisable the webhook
POST/v1/workflows/webhooks/:tokenTrigger a run — no bearer token needed

Tools

MethodPathDescription
GET/v1/toolsList tools
GET/v1/tools/staticList built-in platform tools
POST/v1/toolsRegister a custom tool
GET/v1/tools/:nameGet a tool
PUT/v1/tools/:nameUpdate
DELETE/v1/tools/:nameDelete

Tool keys

Credentials live apart from tool definitions, encrypted at rest.

MethodPathDescription
POST/v1/tool-keysStore a credential
GET/v1/tool-keysList (values never returned)
GET/v1/tool-keys/:keyIdMetadata for one key
PUT/v1/tool-keys/:keyId/metadataRename or re-describe
PUT/v1/tool-keys/:keyId/valueRotate the secret
POST/v1/tool-keys/:keyId/testVerify it works
DELETE/v1/tool-keys/:keyIdDelete
POST/v1/tool-keys/mapMap a key to a tool
DELETE/v1/tool-keys/map/:mappingIdRemove a mapping

Tool permissions

MethodPathDescription
POST/v1/tool-permissions/grantGrant access
POST/v1/tool-permissions/batch-grantGrant many at once
DELETE/v1/tool-permissions/:permissionIdRevoke
GET/v1/tool-permissions/tool/:toolIdWho can use this tool
GET/v1/tool-permissions/subjectWhat this subject can use
GET/v1/tool-permissions/accessible-toolsResolved tool list
GET/v1/tool-permissions/checkCheck one permission
GET/v1/tool-permissions/check-agent-accessCheck an agent's access
POST/v1/tool-permissions/transfer-ownershipHand a tool to someone else

MCP servers

MethodPathDescription
POST/v1/mcp/serversRegister a server
GET/v1/mcp/serversList yours
GET/v1/mcp/servers/marketplaceBrowse the public catalogue
GET/v1/mcp/servers/:serverIdGet
PUT/v1/mcp/servers/:serverIdUpdate
DELETE/v1/mcp/servers/:serverIdDelete
POST/v1/mcp/servers/:serverId/connectConnect
POST/v1/mcp/servers/:serverId/disconnectDisconnect
GET/v1/mcp/servers/:serverId/statusConnection status
POST/v1/mcp/servers/:serverId/syncRe-discover tools, resources, prompts
GET/v1/mcp/servers/:serverId/toolsDiscovered tools
GET/v1/mcp/servers/:serverId/resourcesDiscovered resources
GET/v1/mcp/servers/:serverId/resources/readRead a resource by ?uri=
GET/v1/mcp/servers/:serverId/promptsDiscovered prompts
POST/v1/mcp/servers/:serverId/prompts/:promptNameRender a prompt
GET/v1/mcp/toolsAll MCP tools available to you
GET/v1/mcp/tools/:mcpToolIdOne MCP tool

Skills

MethodPathDescription
GET/v1/skillsList skills
GET/v1/skills/indexCompact index for progressive disclosure
POST/v1/skillsCreate
POST/v1/skills/importImport from a definition
GET/v1/skills/:idGet by ID or slug
PUT/v1/skills/:idUpdate
DELETE/v1/skills/:idDelete
GET/v1/skills/agents/:agentIdSkills attached to an agent
PUT/v1/skills/:id/agents/:agentIdAttach or detach for an agent

Memory

MethodPathDescription
POST/v1/memoryCreate a memory
GET/v1/memory/agents/:agentIdList an agent's memories
GET/v1/memory/agents/:agentId/statsCounts by type
GET/v1/memory/agents/:agentId/retrieveSemantic search — ?query=&limit=
GET/v1/memory/:memoryIdGet
PATCH/v1/memory/:memoryIdUpdate
DELETE/v1/memory/:memoryIdDelete
POST/v1/memory/shared-scopesCreate a shared memory scope
GET/v1/memory/shared-scopes/agents/:agentIdScopes an agent can read

Knowledge spaces

MethodPathDescription
GET/v1/knowledgeList spaces
POST/v1/knowledgeCreate a space
GET/v1/knowledge/providersAvailable knowledge providers
GET/v1/knowledge/searchSearch across spaces
GET/v1/knowledge/:spaceIdGet a space
PATCH/v1/knowledge/:spaceIdUpdate
DELETE/v1/knowledge/:spaceIdDelete
POST/v1/knowledge/:spaceId/grantsGrant access
DELETE/v1/knowledge/:spaceId/grants/:grantIdRevoke access
GET/v1/knowledge/:spaceId/foldersList folders
POST/v1/knowledge/:spaceId/foldersCreate a folder
PATCH/v1/knowledge/:spaceId/folders/:folderIdRename or move
DELETE/v1/knowledge/:spaceId/folders/:folderIdDelete
GET/v1/knowledge/:spaceId/documentsList documents
POST/v1/knowledge/:spaceId/documentsCreate a document
GET/v1/knowledge/:spaceId/documents/:documentIdGet
PATCH/v1/knowledge/:spaceId/documents/:documentIdUpdate
DELETE/v1/knowledge/:spaceId/documents/:documentIdDelete
POST/v1/knowledge/:spaceId/importImport Markdown
GET/v1/knowledge/:spaceId/graphDocument link graph

Files and library

MethodPathDescription
POST/v1/files/uploadUpload a file (multipart)
GET/v1/files/:fileIdFile metadata
GET/v1/files/:fileId/contentFile bytes
GET/v1/libraryList library items
GET/v1/library/:itemIdGet an item
GET/v1/library/:itemId/downloadSigned download
GET/v1/library/:itemId/previewPreview representation
GET/v1/library/:itemId/provenanceWhere the item came from
PATCH/v1/library/:itemIdRename, describe, favourite
DELETE/v1/library/:itemIdDelete
POST/v1/library/:itemId/grantsGrant access
DELETE/v1/library/:itemId/grants/:grantIdRevoke access
POST/v1/library/:itemId/share-linksCreate a public share link
DELETE/v1/library/:itemId/share-links/:shareIdRevoke a share link
GET/v1/library/preferences/storageRead the storage preference
PATCH/v1/library/preferences/storageSet S3 or IPFS
GET/v1/shared/artifacts/:tokenResolve a share link — no auth

Cloud computers

Each agent has one persistent computer.

MethodPathDescription
GET/v1/agents/:agentId/computerStatus
GET/v1/agents/:agentId/computer/configRead the config
PUT/v1/agents/:agentId/computer/configEnable, disable, or resize defaults
POST/v1/agents/:agentId/computer/wakeWake it
POST/v1/agents/:agentId/computer/sleepSleep it
POST/v1/agents/:agentId/computer/restartRestart
POST/v1/agents/:agentId/computer/resizeChange vCPU, memory, storage, GPU
POST/v1/agents/:agentId/computer/execRun a command
POST/v1/agents/:agentId/computer/commandsQueue a command
GET/v1/agents/:agentId/computer/files/readRead a file
POST/v1/agents/:agentId/computer/files/writeWrite files
POST/v1/agents/:agentId/computer/browser/openDrive the browser
POST/v1/agents/:agentId/computer/browser/testCheck a page loads
GET/v1/agents/:agentId/computer/eventsLifecycle events

Code projects

MethodPathDescription
GET/v1/agents/:agentId/projectsList projects
POST/v1/agents/:agentId/projectsCreate
GET/v1/agents/:agentId/projects/:projectIdGet with files
PUT/v1/agents/:agentId/projects/:projectId/filesWrite files
POST/v1/agents/:agentId/projects/:projectId/publishBuild and publish a preview
POST/v1/agents/:agentId/projects/:projectId/verifyVerify a build
POST/v1/agents/:agentId/projects/:projectId/exportExport to the agent computer
POST/v1/agents/:agentId/projects/:projectId/githubPush to GitHub
GET/v1/previews/:slugServe a published preview — no auth

OAuth connections

MethodPathDescription
GET/v1/oauth/providersList providers — no auth
GET/v1/oauth/providers/:providerKeyProvider detail — no auth
POST/v1/oauth/connectStart a flow; returns an authorization URL
GET/v1/oauth/callback/:providerKeyProvider redirect target
GET/v1/oauth/connectionsList connections
GET/v1/oauth/connections/:connectionIdGet one
PUT/v1/oauth/connections/:connectionIdRename
POST/v1/oauth/connections/:connectionId/refreshForce a token refresh
GET/v1/oauth/connections/:connectionId/testCheck the token is live
DELETE/v1/oauth/connections/:connectionIdRevoke and delete tokens

Agent-to-Agent

MethodPathDescription
GET/.well-known/agent.json?agentId=…Agent Card — no auth
GET/v1/a2a/:agentId/.well-knownAgent Card by path — no auth
POST/v1/a2a/:agentIdJSON-RPC 2.0 endpoint
GET/v1/a2a/:agentId/tasksRecent A2A tasks
GET/v1/a2a/:agentId/tasks/:taskId/streamSSE task updates

JSON-RPC methods: tasks/send, tasks/sendSubscribe, tasks/get, tasks/cancel.

Spaces

MethodPathDescription
GET/v1/spacesList spaces
GET/v1/spaces/publicPublic spaces
POST/v1/spacesCreate
GET/v1/spaces/:spaceIdGet
GET/v1/spaces/:spaceId/fullSpace with members and messages
PUT/v1/spaces/:spaceIdUpdate
DELETE/v1/spaces/:spaceIdDelete
POST/v1/spaces/:spaceId/rtc-ticketMint a WebRTC join ticket
GET/v1/spaces/:spaceId/membersList members
POST/v1/spaces/:spaceId/membersAdd a member
PUT/v1/spaces/:spaceId/members/:memberIdUpdate a member
DELETE/v1/spaces/:spaceId/members/:memberIdRemove a member
GET/v1/spaces/:spaceId/messagesRead messages
POST/v1/spaces/:spaceId/messagesPost a message
PUT/v1/spaces/:spaceId/messages/:messageIdEdit
DELETE/v1/spaces/:spaceId/messages/:messageIdDelete
GET/v1/spaces/:spaceId/subscribeSubscribe to updates
GET/v1/spaces/:spaceId/unsubscribeUnsubscribe
GET/v1/spaces-stream/:spaceId/composite.pngComposite video frame

Wallets

MethodPathDescription
POST/v1/walletsCreate a wallet
GET/v1/wallets/agent/:agentIdList an agent's wallets
GET/v1/wallets/agent/:agentId/primaryPrimary wallet
GET/v1/wallets/:walletIdGet
GET/v1/wallets/:walletId/balanceUSDC and ETH balance
POST/v1/wallets/:walletId/transferSend funds
POST/v1/wallets/agent/:agentId/x402-fetchFetch a URL, paying any x402 challenge
DELETE/v1/wallets/:walletIdDeactivate

Provenance

MethodPathDescription
GET/v1/provenance/sessions/:sessionIdSources and contributors for a session
GET/v1/provenance/scopes/:scopeType/:scopeIdReport for any scope
GET/v1/provenance/traces/:traceId/bundlePortable EAA bundle
POST/v1/provenance/traces/:traceId/anchorAnchor the bundle commitment on-chain

Credits and billing

MethodPathDescription
GET/v1/credits/balanceCurrent balance
GET/v1/credits/ledgerLedger entries
GET/v1/credits/summaryRolled-up usage
GET/v1/credits/campaignsActive campaigns
POST/v1/credits/campaigns/claimClaim a campaign
GET/v1/credits/transfersGifts sent and received
POST/v1/credits/giftsGift credits
POST/v1/credits/grantsGrant credits (admin)
POST/v1/credits/debitsDebit credits (admin)
GET/v1/billing/catalogPlans and packs — no auth
GET/v1/billing/subscriptionYour subscription
GET/v1/billing/entitlementsResolved plan entitlements
GET/v1/billing/invoicesInvoices
GET/v1/billing/payment-methodsSaved payment methods
POST/v1/billing/checkout/subscriptionStart a plan checkout
POST/v1/billing/checkout/topupBuy a credit pack
POST/v1/billing/portalOpen the billing portal

Observability

MethodPathDescription
GET/v1/usage/agents/:agentIdToken usage and cost — ?from=&to=
GET/v1/usage/sessions/:sessionIdUsage for one session
GET/v1/logs/agents/:agentIdActivity log entries
GET/v1/logs/agents/:agentId/observabilityTraces and spans
GET/v1/activity/eventsPlatform activity feed

Platform

MethodPathDescription
GET/healthLiveness — no auth
GET/v1/modelsModel registry — no auth
GET/v1/auth/meIdentify the caller
POST/v1/auth/api-keysCreate a principal key
GET/v1/auth/api-keysList principal keys
DELETE/v1/auth/api-keys/:idRevoke
GET/v1/flagsFeature flags for the caller
GET/v1/flags/:keyEvaluate one flag
GET/v1/providersCapability provider configuration
PUT/v1/providers/:capabilityConfigure a capability provider
DELETE/v1/providers/:capabilityReset to the default
GET/v1/ui-pluginsList Commons apps
PUT/v1/ui-pluginsRegister or update an app draft
GET/v1/ui-plugins/capabilitiesCapability catalog
PUT/v1/ui-plugins/:pluginId/statusEnable (with grants) or turn off an app
PUT/v1/ui-plugins/:pluginId/grantsChange what an app may do
PUT/v1/ui-plugins/:pluginId/appearanceSet or reset the app icon
GET/v1/ui-plugins/:pluginId/connectionsExternal connections and their status
PUT/v1/ui-plugins/:pluginId/connections/:keySave a connection key or turn it off
GET/v1/ui-plugins/:pluginId/storageStorage provider for app data
PUT/v1/ui-plugins/:pluginId/storageUse Commons, Supabase or MongoDB storage
POST/v1/ui-plugins/:pluginId/gatewayApp bridge calls that run on the server
GET/v1/ui-plugins/layoutPinned apps by page
PUT/v1/ui-plugins/layoutPin apps for a page or all pages
DELETE/v1/ui-plugins/layout?scope=Use the all-pages pins again
POST/v1/audio/transcriptionsTranscribe audio
POST/v1/goalsCreate a goal
GET/v1/goals/:goalIdGet a goal
PUT/v1/goals/:goalIdUpdate progress
POST/v1/liaisonCreate a liaison agent
POST/v1/liaison/interactInteract with a liaison
GET/v1/compute/*Common OS compute, proxied by the gateway

OpenAPI

A development server publishes Swagger at http://localhost:3001/docs. It is disabled in production.

Previous

Credits & Billing

Next

TypeScript SDK

On this page