Skip to main content
Agents are deployed AI assistants that run in sandboxed containers. Each agent has a unique ID (prefixed with agt_) and can be referenced by name or ID.

​
Base URL

All agent endpoints are under: 
https://api.superserve.ai/v1/agents

​
Deploy Agent

Deploy a new agent to Superserve. 
POST /v1/agents
Authorization: Bearer YOUR_API_TOKEN
Content-Type: multipart/form-data
Request (multipart/form-data):
​
file
file
required
Tarball (.tar.gz) containing the agent code and dependencies
​
name
string
required
Agent name (must be unique within your account)
​
command
string
required
Command to start the agent (e.g., bun run index.ts)
​
config
string
required
JSON-encoded configuration object from superserve.yaml
Response:
​
id
string
required
Agent ID (prefixed with agt_)
​
name
string
required
Agent name
​
command
string | null
required
Start command for the agent
​
environment_keys
string[]
required
Environment variable names available to the agent
​
required_secrets
string[]
required
Secret keys that must be set before the agent can run
​
deps_status
string
required
Dependency installation status: pending, installing, ready, or failed
​
deps_error
string | null
required
Error message if dependency installation failed
​
created_at
string
required
ISO 8601 timestamp when the agent was created
​
updated_at
string
required
ISO 8601 timestamp when the agent was last updated
Example Response: 
{
  "id": "agt_abc123def456",
  "name": "my-agent",
  "command": "bun run index.ts",
  "environment_keys": ["ANTHROPIC_API_KEY"],
  "required_secrets": ["ANTHROPIC_API_KEY"],
  "deps_status": "ready",
  "deps_error": null,
  "created_at": "2026-03-09T10:00:00Z",
  "updated_at": "2026-03-09T10:00:00Z"
}

​
List Agents

Retrieve all agents in your account. 
GET /v1/agents?limit=100
Authorization: Bearer YOUR_API_TOKEN
Query Parameters:
​
limit
string
default:"100"
Maximum number of agents to return
Response:
​
agents
array
required
Array of agent objects (same schema as deploy response)
Example Response: 
{
  "agents": [
    {
      "id": "agt_abc123",
      "name": "my-agent",
      "command": "bun run index.ts",
      "environment_keys": ["ANTHROPIC_API_KEY"],
      "required_secrets": ["ANTHROPIC_API_KEY"],
      "deps_status": "ready",
      "deps_error": null,
      "created_at": "2026-03-09T10:00:00Z",
      "updated_at": "2026-03-09T10:00:00Z"
    }
  ]
}

​
Get Agent

Retrieve details for a specific agent. 
GET /v1/agents/{agent_id}
Authorization: Bearer YOUR_API_TOKEN
Path Parameters:
​
agent_id
string
required
Agent ID (e.g., agt_abc123)
Response: Same schema as deploy response. Example: 
{
  "id": "agt_abc123",
  "name": "my-agent",
  "command": "bun run index.ts",
  "environment_keys": ["ANTHROPIC_API_KEY"],
  "required_secrets": ["ANTHROPIC_API_KEY"],
  "deps_status": "ready",
  "deps_error": null,
  "created_at": "2026-03-09T10:00:00Z",
  "updated_at": "2026-03-09T10:00:00Z"
}

​
Delete Agent

Delete an agent and all its sessions. 
DELETE /v1/agents/{agent_id}
Authorization: Bearer YOUR_API_TOKEN
Path Parameters:
​
agent_id
string
required
Agent ID (e.g., agt_abc123)
Response: 204 No Content on success.

​
Deployment Status

The deps_status field indicates the current state of the agent’s dependency installation:
StatusDescription
pendingDependencies queued for installation
installingDependencies currently being installed
readyAgent is ready to receive requests
failedDependency installation failed (see deps_error)
You cannot create sessions or runs with an agent until deps_status is ready.

​
Error Responses

​
status
number
HTTP status code
​
detail
string
Error message
​
details
object
Additional error context
Common Errors:
StatusMessageHint
401Not authenticatedRun superserve login to authenticate
404Agent not foundRun superserve agents list to see your agents
409Agent already existsUse a different name or delete the existing agent
422Invalid inputCheck your request parameters

Build docs developers (and LLMs) love

Get started for freeTalk to us