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_slug": "claude-code",
"agentfile_layer": "PROMPT \"Fix the login bug\"\nCONFIG permission_mode = \"plan\""
}'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_slug": "claude-code",
"runner_id": "550e8400-e29b-41d4-a716-446655440000",
"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_slug": "claude-code",
"runner_id": "550e8400-e29b-41d4-a716-446655440000",
"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 |
|---|---|---|---|
| agent_slug | string | Required | Agent identifier (e.g., claude-code, aider) |
| agentfile_layer | string | Optional | AgentFile Layer — SSOT for PROMPT, MODE, CONFIG, REPO, BRANCH, CREDENTIAL |
| runner_id | integer | Optional | ID of the runner to create the pod on |
| ticket_slug | string | Optional | Ticket slug to link (e.g., AM-123) |
| alias | string | Optional | Display name for the pod (max 100 chars) |
Response Example
{
"pod": {
"pod_key": "pod-xyz789",
"status": "initializing",
"agent_slug": "claude-code",
"created_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"
}