Pods API
Manage AgentPods programmatically. Create, list, and terminate Pods through the REST API.
Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /pods | pods:read | List all pods |
GET | /pods/:key | pods:read | Get pod details by key |
POST | /pods | pods:write | Create a new pod |
POST | /pods/:key/terminate | pods:write | Terminate a pod |
Code Examples
List all running pods
curl -X GET \ "https://your-domain.com/api/v1/ext/orgs/my-org/pods" \ -H "X-API-Key: amk_your_api_key_here"
Create a new pod
curl -X POST \
"https://your-domain.com/api/v1/ext/orgs/my-org/pods" \
-H "X-API-Key: amk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"agent_type_id": "claude-code",
"runner_id": "runner-uuid",
"initial_prompt": "Fix the login bug"
}'Endpoint Details
GET /pods
Retrieve a paginated list of pods in the organization. Supports filtering by status.
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| status | string | Optional | - | Filter by pod status (e.g., running, terminated) |
| limit | integer | Optional | 20 | Maximum number of results to return |
| offset | integer | Optional | 0 | Number of results to skip for pagination |
Response Example
{
"pods": [
{
"key": "pod-abc123",
"status": "running",
"agent_type_id": "claude-code",
"runner_id": "550e8400-e29b-41d4-a716-446655440000",
"initial_prompt": "Fix the login bug",
"repository_id": 1,
"branch": "main",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:35:00Z"
}
],
"total": 42,
"limit": 20,
"offset": 0
}GET /pods/:key
Retrieve detailed information about a specific pod by its unique key.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | Required | The unique key identifier of the pod |
Response Example
{
"pod": {
"key": "pod-abc123",
"status": "running",
"agent_type_id": "claude-code",
"runner_id": "550e8400-e29b-41d4-a716-446655440000",
"initial_prompt": "Fix the login bug",
"repository_id": 1,
"branch": "main",
"ticket_slug": "AM-42",
"channel_id": 5,
"sandbox_type": "worktree",
"auto_close": false,
"pod_timeout_minutes": 60,
"max_turns": 100,
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:35:00Z"
}
}POST /pods
Create a new AgentPod on a specified runner. The pod will be initialized with the given configuration and start executing.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| runner_id | string | Required | ID of the runner to create the pod on |
| agent_type_id | string | Optional | Agent type identifier (e.g., claude-code, aider) |
| initial_prompt | string | Optional | Initial prompt or task for the agent |
| repository_id | integer | Optional | Repository to associate with the pod |
| branch | string | Optional | Git branch to work on |
| ticket_slug | string | Optional | Ticket slug to link (e.g., AM-123) |
| channel_id | integer | Optional | Channel to associate with the pod |
| sandbox_type | string | Optional | Sandbox type: worktree or tempdir |
| environment_variables | object | Optional | Key-value pairs of environment variables |
| custom_agent_command | string | Optional | Custom command to launch the agent |
| custom_agent_args | string[] | Optional | Arguments for the custom agent command |
| custom_mcp_config | object | Optional | Custom MCP server configuration (JSON) |
| auto_close | boolean | Optional | Whether the pod should auto-close after task completion |
| auto_close_delay_seconds | integer | Optional | Delay in seconds before auto-closing |
| pod_timeout_minutes | integer | Optional | Maximum lifetime of the pod in minutes |
| max_turns | integer | Optional | Maximum number of agent turns |
Response Example
{
"pod": {
"key": "pod-xyz789",
"status": "creating",
"agent_type_id": "claude-code",
"runner_id": "550e8400-e29b-41d4-a716-446655440000",
"initial_prompt": "Fix the login bug",
"repository_id": 1,
"branch": "feature/auth",
"sandbox_type": "worktree",
"auto_close": true,
"auto_close_delay_seconds": 30,
"pod_timeout_minutes": 60,
"max_turns": 100,
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
}POST /pods/:key/terminate
Terminate a running pod. The pod process will be stopped and resources released.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | Required | The unique key identifier of the pod to terminate |
Response Example
{
"message": "Pod terminated"
}