/
DE
desplega-ai
/
Agent Swarm API
Search skmtc…
⌘K
Docs
Sign in
Sign in
APIs
Generators
Stacks
Projects
Docs
History
Schema
Sources
Checked 2h ago · Updated 3h ago
latest
OpenAPI 3.1.0
raw.githubusercontent.com
2026-08-20
351
71
1.3 MB
d06bca6c3ff5
Active Sessions
8
get
List active sessions
post
Create a new active session
delete
Delete active session by task ID
delete
Delete active session by ID
put
Update heartbeat for an active session
put
Update provider session ID on an active session
post
Clean up stale sessions
post
Recover orphaned in-progress tasks for an agent
Agents
13
get
List all agents
post
Register or re-register an agent
patch
Re-assign an agent's harness_provider (live)
patch
Update an agent's runtime harness and default model
put
Update agent name
get
Fetch agent + global setup scripts for Docker entrypoint
get
List runtime instances serving an agent
put
Update agent profile (role, description, capabilities, etc.)
put
Update agent last activity timestamp
get
Get a single agent
get
Single-agent credential-status snapshot for the dashboard
put
Worker self-report of credential readiness (Phase 3 boot loop)
get
Bulk credential-status across all agents (powers the dashboard)
API Keys
8
post
Record which API key was used for a task
post
Mark an API key as rate-limited
post
Record provider-emitted rate-limit window telemetry for an API key
get
Get available (non-rate-limited) key indices for a credential type
get
Get all API key status records
get
Get aggregated cost data per API key
patch
Set or clear the human-friendly label on a pooled credential
post
Clear rate-limited status for a key after a successful use proves it is healthy
ApprovalRequests
4
get
List approval requests with optional filters
post
Create a new approval request
get
Get approval request details
post
Submit a response to an approval request
Apps
20
get
Get app user configuration
put
Set app user configuration
get
List apps
post
Create an app
get
List app definition versions
get
Get an app definition version
post
Rollback an app definition
get
Get an app
put
Update an app
delete
Delete an app and all of its rows
patch
Patch an app
get
List app model rows
post
Create an app model row
post
Bulk-create app model rows
get
Get an app model row
delete
Delete an app model row
patch
Patch an app model row
get
Run a named app query
post
Run a custom app action
post
Sync an app's declared sources
Assets
6
get
Audit asset namespace invariants
get
List lightweight cross-entity asset summaries
post
Register a logical namespace for a provider object
patch
Move an app to another logical namespace
patch
Move a script to another logical namespace
patch
Move an asset to another logical namespace
Budgets
5
get
List all configured budget rows
get
List recent budget refusal notifications
get
Get a single budget row
put
Create or update a budget row
delete
Delete a budget row
Config
7
get
Get resolved config (merged global + agent + repo scopes)
get
Check which of the given env var keys are currently set in process.env (presence only, no values)
post
Reload global swarm_config into process.env (override=true) and re-init integrations (Slack, GitHub, Linear, AgentMail)
get
Get a single config entry by ID
delete
Delete a config entry by ID (including legacy reserved rows for cleanup). Global-scope deletes auto-trigger an integrations reload.
get
List config entries with optional filters
put
Create or update a config entry (reserved env-only keys are rejected). Global-scope writes auto-trigger an integrations reload (debounced ~250ms) so Slack/GitHub/Linear/Jira/AgentMail pick up new credentials without an explicit /api/config/reload call.
Core
2
post
Report agent liveness
post
Mark an agent or runtime offline on shutdown
Debug
1
post
Execute a read-only SQL query
Ecosystem
1
get
Get PM2 ecosystem config for agent services
Events
4
get
Query events with filters
post
Store a single event
post
Store multiple events in a batch
get
Get event counts grouped by event name
External APIs
1
post
Invoke an externally-exposed swarm script
Favorites
2
get
List favorites for the authenticated principal
put
Set favorite state for an item
FS
9
get
Get active file-storage provider capabilities
post
Ensure agent-scoped agent-fs credentials for the current agent
post
Invite an external member into the agent-fs shared org
get
List task file attachments
post
Upload a binary task file attachment
get
Get task file attachment metadata
delete
Delete a task file attachment
get
Download raw task file bytes
get
Create a provider signed GET URL for a task file
Heartbeat
2
post
Trigger an immediate heartbeat sweep
post
Trigger an immediate heartbeat checklist check
Inbox State
2
get
List inbox-item state rows for a user
patch
Upsert per-user dismiss/snooze/done state for an inbox item
Integrations
2
post
Test the claude-managed integration: resolves ANTHROPIC_API_KEY + MANAGED_AGENT_ID from swarm_config and calls beta.agents.retrieve.
get
Get server-derived config for end-user MCP clients.
KV
10
get
Get a KV entry by key (namespace resolved from request headers)
put
Upsert a KV entry by key (namespace resolved from request headers)
delete
Delete a KV entry by key (namespace resolved from request headers)
post
Atomically increment an integer KV entry (header-resolved namespace)
get
List KV entries in the header-resolved namespace
get
Get a KV entry by explicit namespace + key
put
Upsert a KV entry by explicit namespace + key
delete
Delete a KV entry by explicit namespace + key
post
Atomically increment an integer KV entry (explicit namespace)
get
List KV entries in an explicit namespace
MCP OAuth
8
get
Probe OAuth metadata (PRMD + AS) for an MCP server
get
Get the current OAuth connection status for an MCP server
get
Start an OAuth flow. Redirects to the provider.
get
Build an OAuth authorize URL. Returns JSON so the browser can navigate without losing the Bearer auth header.
get
OAuth redirect target. Exchanges code -> tokens and redirects back to dashboard.
post
Force-refresh the access token for an MCP server
delete
Revoke and delete the OAuth token for an MCP server
post
Register a pre-existing OAuth client (DCR fallback)
MCP Servers
8
get
List MCP servers with optional filters
post
Create a new MCP server
get
Get MCP server by ID
put
Update an MCP server
delete
Delete an MCP server
post
Install MCP server for an agent
delete
Uninstall MCP server for an agent
get
Get all MCP servers installed for an agent
Memory
12
post
Ingest content into memory system (async embedding)
post
Search memories by natural language query
post
Edit a single memory in place while preserving its ID and usefulness posterior. Modes: 'replace' overwrites entire content; 'exact' performs surgical find-and-replace of oldString→newString (fails if missing or ambiguous)
post
Re-embed all memories using the current embedding provider
post
List or semantically search memories across all agents (debug/admin)
get
Report memory vector index health and retrieval mode
get
Windowed memory usefulness analytics: retrieval volume, per-arm breakdown, citation rate per source, posterior movement
get
Get a single memory by ID
delete
Delete a single memory by ID (debug/admin)
post
Submit RatingEvents to update memory usefulness posteriors
get
List memories retrieved for a task or session (rater input)
get
List references-source edges for a memory
Metrics
9
get
List metric definitions
post
Create a metric definition
get
Get a metric definition
put
Update a metric definition
delete
Delete a metric definition
post
Run a metric definition
get
List metric definition versions
get
Get a metric definition version
get
Get the metric definition JSON Schema
OAuth
6
post
Locked keep-warm refresh sweep across all Codex OAuth pool slots
post
Acquire a cross-process OAuth refresh lock
delete
Release a cross-process OAuth refresh lock if still held by the given owner
get
Single static OAuth redirect target (state-keyed, all flows)
get
The static OAuth callback URL to register with providers (pre-creation display)
get
Legacy per-provider OAuth redirect target (delegates to the static callback)
Pages
17
get
Cookie-gated proxy to the swarm API (used by db-backed page iframes)
put
Cookie-gated proxy to the swarm API (PUT)
post
Cookie-gated proxy to the swarm API (POST)
delete
Cookie-gated proxy to the swarm API (DELETE)
patch
Cookie-gated proxy to the swarm API (PATCH)
get
List pages
post
Create a new page
get
Get a page by ID
put
Update an existing page
delete
Delete a page (and all version history)
get
Resolve a page by slug
post
Launch a page session (issues HttpOnly cookie)
get
List JSON-page action allowlist (with param JSON Schemas)
get
List version snapshots for a page
get
Get a single page-version snapshot
get
Render a page (HTML inline; JSON redirects to SPA)
get
Page metadata + body as JSON (used by SPA renderer)
Poll
2
get
Poll for triggers (tasks, mentions)
post
Commit channel activity cursors after successful processing
Pricing
6
get
Get the live model catalog for the picker-reachable providers
get
List every pricing row across all providers
get
List pricing history for a (provider, model, tokenClass) triple
post
Append a new pricing row
get
Get the currently active pricing row
delete
Delete a pricing row (typo correction)
PromptTemplates
10
get
Resolve a prompt template for a given event type and scope chain
get
List all registered event types with their available variables
post
Dry-run render a template with provided variables
post
Full scope-aware template resolution with interpolation (used by workers via HTTP)
post
Checkout a specific version of a prompt template from history
post
Reset a prompt template to its code-defined default
get
Get a single prompt template with its version history
delete
Delete a prompt template override
get
List prompt templates with optional filters
put
Create or update a prompt template override
Repos
5
get
Get a repo by ID
put
Update a repo
delete
Delete a repo
get
List repos with optional filters
post
Create a new repo
Schedules
7
get
List schedules
post
Create a new schedule
post
Run a schedule immediately
get
Get a schedule by ID
put
Update a schedule
delete
Delete a schedule
patch
Patch a schedule
Script Connections
21
get
List script connections
post
Create or update a script connection
get
Get script connection detail
post
Refresh a script connection
post
Enable or disable a script connection
get
List standalone script credential bindings
post
Create or update a script credential binding
get
List OAuth apps for script credential bindings
post
Create or update an OAuth app for script credential bindings
get
List curated OAuth presets for app-creation pickers
post
Discover OAuth endpoints from provider metadata
delete
Delete an OAuth app and its tokens
post
Build an OAuth authorization URL for a labeled authorization
get
List the labeled authorizations for an OAuth app (never token material)
delete
Revoke (best-effort) and delete a single OAuth authorization
post
Force-refresh a single OAuth authorization (never returns token values)
get
Proxy integrations.sh catalog entries
get
Proxy integrations.sh per-domain surface details (trimmed for the Add Connection flow)
delete
Disconnect an OAuth app: delete stored tokens (best-effort remote revocation when a revocation endpoint is known)
post
Force-refresh the stored OAuth tokens for a provider (never returns token values)
post
Invoke a tool on an MCP script connection
Script Runs
10
get
List script workflow runs
post
Launch a durable script workflow run
get
Get a script workflow run with journal
delete
Cancel a script workflow run
get
Get a script run journal step
post
Write a script run journal step
post
Record a script run heartbeat
post
Update script run status from subprocess
post
Execute a raw LLM call for a script workflow
post
Create or wait for a script workflow agent task step
Scripts
16
post
Create or update a reusable script
post
Run a reusable or inline script
post
Search reusable scripts
delete
Delete a reusable script
get
Get script signature and authoring types
get
List saved scripts
get
Get script SDK and stdlib type definitions
get
Get a saved script by id
get
List versions of a saved script
get
List external API endpoints for a script
post
Expose a script as an external HTTP API endpoint
get
Reveal an endpoint's bearer token
delete
Delete an external API endpoint
patch
Enable/disable or relabel an external API endpoint
post
Rotate an endpoint's bearer token
post
Generic MCP tool proxy for the scripts SDK bridge
Session Data
7
post
Store session logs
get
Get session logs for a task
get
Query session costs with filters
post
Store session cost record
get
Aggregated session cost summary
get
Four-metric per-person attribution (problems initiated/shipped, reach)
get
Cost today and month-to-date for dashboard
Sessions
2
get
List recent task sessions (root tasks + chain summary)
get
Get a session — root task + the entire descendant chain
Skills
17
get
List skills with optional filters
post
Create a new skill
get
Get skill by ID
put
Update a skill
delete
Delete a skill
get
List bundled files for a skill
post
Bulk upsert bundled files for a skill
get
Get a bundled skill file
put
Upsert a bundled skill file
delete
Delete a bundled skill file
post
Install skill for an agent
delete
Uninstall skill for an agent
post
Install a remote skill from GitHub
post
Trigger remote skill sync
post
Sync installed skills to agent filesystem
get
Get all skills installed for an agent
get
Compute a stable signature over an agent's installed skills
Stats
6
get
List agent logs
get
Dashboard summary stats
get
Lightweight swarm-wide counts
get
List all registered services
get
List scheduled tasks
get
Get concurrent session context for lead awareness
Status
2
get
Identity + setup readiness + live activity for the swarm dashboard
post
Live-test the harness provider's credentials
Task Templates
1
get
List task templates ('To start' bucket)
Tasks
21
get
Get context usage history for a task
post
Record a context usage snapshot for a task
get
List tasks with filters
post
Create a new task
put
Update provider session ID and harness metadata for a task
post
Cancel a pending or in-progress task
post
Deliver a steering message to a running task
get
List steering messages for a task
get
List pending steering messages for the current worker
post
Mark a steering message delivered
post
Mark a steering message handled
post
Promote an undeliverable steering message
get
Get task details with logs and attachments
post
Update task progress text
post
Mark task as completed or failed (runner endpoint)
get
Get paused tasks for this agent
post
Pause an in-progress task
post
Resume a paused task
post
Supersede an in-progress task (terminate + spawn resume follow-up)
patch
Update VCS (PR/MR) info for a task
patch
Set or clear a task's display title (session rename)
Trackers
14
get
Redirect to Atlassian OAuth consent screen
get
Handle Jira OAuth callback (resolves cloudId via accessible-resources)
get
Jira connection status, cloudId/siteUrl, token expiry, expected webhook URL, scope/token-config flags
post
Force a Jira OAuth token refresh and return the updated status payload. Useful when an agent observes an expired token via tracker-status / db-query and wants to recover without restarting the server or re-running 3LO.
post
Receive Jira webhook events (URL-token authenticated). Phase 2 stub — Phase 3 fills in dispatch.
post
Register a Jira dynamic webhook (admin only)
delete
Delete a Jira dynamic webhook (admin only)
delete
Fully disconnect Jira: delete all webhooks, drop tokens, clear metadata
get
Redirect to Linear OAuth consent screen
get
Handle Linear OAuth callback
get
Linear connection status, token expiry, workspace info, expected webhook URL
post
Force a Linear OAuth token refresh and return the updated status payload. Useful when an agent observes an expired token and wants to recover without restarting the server or re-running OAuth.
post
Handle Linear webhook events (signature-verified)
delete
Fully disconnect Linear: revoke OAuth grant + drop tokens
Users
13
get
Resolve the authenticated principal behind the presented bearer
get
List all users with identities, token summaries and recent events
post
Create a new user (optionally with initial identity links)
get
List unmapped external identities (kv-backed triage queue)
post
Resolve an unmapped identity — link to an existing user or create a new one
get
Get a user by ID with identities, token summaries and recent events
patch
Update an existing user (profile / budget / status / email-aliases / identities)
post
Mint a one-time plaintext MCP token for a user
delete
Revoke a user's MCP token
post
Merge another user into this one — moves identities + email aliases, deletes source
get
Paginated identity-event timeline for a user (DESC by createdAt)
post
Link a new (kind, externalId) identity to this user
delete
Remove a (kind, externalId) identity link from this user
Webhooks
5
post
Handle GitHub webhook events
post
Handle GitLab webhook events
post
Handle AgentMail webhook events
post
Handle native Kapso/WhatsApp webhook events
post
Trigger workflow via webhook
WorkflowEvents
2
post
Fire a run-scoped event signal
post
Fire a global workflow event signal
Workflows
17
get
List all workflows
post
Create a new workflow
get
Get a workflow by ID
put
Update a workflow
delete
Delete a workflow
patch
Patch a workflow definition (create/update/delete nodes)
patch
Patch a single node in a workflow definition
post
Trigger a workflow execution
post
Validate a payload against the workflow's triggerSchema (no run)
get
List runs for a workflow
get
Get a workflow run with steps (includes retry columns)
post
Retry a failed workflow run
post
Cancel a running or waiting workflow run
get
List all executor types with their config and output schemas
get
Get a specific executor type with its schemas
get
List version history for a workflow
get
Get a specific version snapshot of a workflow
Active Sessions
List active sessions
get
/api/active-sessions
Query parameters
agentId
string
Response
Active session list
object
required
sessions
ActiveSession[]
required