Skip to content
Core ConceptsCLI ReferenceAPI Reference
AGH RuntimeAPI Reference

Sessions

AGH Sessions HTTP endpoints.

Audience
Operators running durable agent work
Focus
API Reference guidance shaped for scanability, day-two clarity, and operator context.

Spawn a narrowed child session for the calling agent

POST/api/agent/spawn

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/agent/spawn" \  -H "Content-Type: application/json" \  -d '{    "agent_name": "string",    "auto_stop_on_parent": true,    "permissions": {      "mcp_servers": [        "string"      ],      "network_channels": [        "string"      ],      "sandbox_profiles": [        "string"      ],      "skills": [        "string"      ],      "tools": [        "string"      ],      "workspace_paths": [        "string"      ]    },    "spawn_role": "string",    "ttl_seconds": 0  }'
{
  "spawn": {
    "lineage": {
      "auto_stop_on_parent": true,
      "parent_session_id": "string",
      "permission_policy": {
        "mcp_servers": [
          "string"
        ],
        "network_channels": [
          "string"
        ],
        "sandbox_profiles": [
          "string"
        ],
        "skills": [
          "string"
        ],
        "tools": [
          "string"
        ],
        "workspace_paths": [
          "string"
        ]
      },
      "root_session_id": "string",
      "spawn_budget": {
        "max_active_per_workspace": 0,
        "max_children": 0,
        "max_depth": 0,
        "ttl_seconds": 0
      },
      "spawn_depth": 0,
      "spawn_role": "string",
      "ttl_expires_at": "2019-08-24T14:15:22Z"
    },
    "permissions": {
      "mcp_servers": [
        "string"
      ],
      "network_channels": [
        "string"
      ],
      "sandbox_profiles": [
        "string"
      ],
      "skills": [
        "string"
      ],
      "tools": [
        "string"
      ],
      "workspace_paths": [
        "string"
      ]
    },
    "session": {
      "acp_caps": {
        "config_options": [
          {
            "current": "string",
            "description": "string",
            "id": "string",
            "kind": "string",
            "label": "string",
            "values": [
              {
                "description": "string",
                "label": "string",
                "value": "string"
              }
            ]
          }
        ],
        "supported_models": [
          "string"
        ],
        "supported_modes": [
          "string"
        ],
        "supports_load_session": true
      },
      "acp_session_id": "string",
      "activity": {
        "current_tool": "string",
        "deadline_at": "2019-08-24T14:15:22Z",
        "elapsed_ms": 0,
        "elapsed_seconds": 0,
        "idle_seconds": 0,
        "iteration_current": 0,
        "iteration_max": 0,
        "last_activity_at": "2019-08-24T14:15:22Z",
        "last_activity_detail": "string",
        "last_activity_kind": "string",
        "last_progress_at": "2019-08-24T14:15:22Z",
        "tool_call_id": "string",
        "turn_id": "string",
        "turn_source": "string",
        "turn_started_at": "2019-08-24T14:15:22Z"
      },
      "agent_name": "string",
      "attach_expires_at": "2019-08-24T14:15:22Z",
      "attachable": true,
      "attached_to": "string",
      "badge": "string",
      "channel": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "failure": {
        "crash_bundle_path": "string",
        "kind": "string",
        "summary": "string"
      },
      "health": {
        "active_prompt": true,
        "agent_name": "string",
        "attachable": true,
        "eligible_for_wake": true,
        "health": "healthy",
        "ineligibility_reason": "session_prompt_active",
        "last_activity_at": "2019-08-24T14:15:22Z",
        "last_error": "string",
        "last_presence_at": "2019-08-24T14:15:22Z",
        "session_id": "string",
        "state": "idle",
        "updated_at": "2019-08-24T14:15:22Z",
        "workspace_id": "string"
      },
      "id": "string",
      "lineage": {
        "auto_stop_on_parent": true,
        "parent_session_id": "string",
        "permission_policy": {
          "mcp_servers": [
            "string"
          ],
          "network_channels": [
            "string"
          ],
          "sandbox_profiles": [
            "string"
          ],
          "skills": [
            "string"
          ],
          "tools": [
            "string"
          ],
          "workspace_paths": [
            "string"
          ]
        },
        "root_session_id": "string",
        "spawn_budget": {
          "max_active_per_workspace": 0,
          "max_children": 0,
          "max_depth": 0,
          "ttl_seconds": 0
        },
        "spawn_depth": 0,
        "spawn_role": "string",
        "ttl_expires_at": "2019-08-24T14:15:22Z"
      },
      "model": "string",
      "name": "string",
      "provider": "string",
      "reasoning_effort": "string",
      "sandbox": {
        "backend": "string",
        "instance_id": "string",
        "last_sync_error": "string",
        "profile": "string",
        "provider_state_json": null,
        "sandbox_id": "string",
        "state": "string"
      },
      "state": "starting",
      "stop_detail": "string",
      "stop_reason": "completed",
      "type": "user",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string",
      "workspace_path": "string"
    }
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Prune materialized Memory v2 session ledger state

POST/api/memory/sessions/prune

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/sessions/prune" \  -H "Content-Type: application/json" \  -d '{    "older_than_hours": 0  }'
{
  "dry_run": true,
  "pruned_events": 0,
  "pruned_sessions": 0
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Repair materialized Memory v2 session ledgers

POST/api/memory/sessions/repair

Response Body

application/json

application/json

curl -X POST "https://example.com/api/memory/sessions/repair"
{
  "completed_at": "2019-08-24T14:15:22Z",
  "repaired_ledgers": 0,
  "skipped_ledgers": 0
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

List sessions

GET/api/sessions

Query Parameters

workspace?string

Workspace id or path

include_health?boolean

Include metadata-only session health when available

resumable?boolean

Only list sessions eligible for explicit attach

sort?string

Optional sort key. Use last_activity with resumable=true.

limit?integer

Maximum sessions to return when filtering resumable sessions

Formatint32

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/sessions"
{
  "sessions": [
    {
      "acp_caps": {
        "config_options": [
          {
            "current": "string",
            "description": "string",
            "id": "string",
            "kind": "string",
            "label": "string",
            "values": [
              {
                "description": "string",
                "label": "string",
                "value": "string"
              }
            ]
          }
        ],
        "supported_models": [
          "string"
        ],
        "supported_modes": [
          "string"
        ],
        "supports_load_session": true
      },
      "acp_session_id": "string",
      "activity": {
        "current_tool": "string",
        "deadline_at": "2019-08-24T14:15:22Z",
        "elapsed_ms": 0,
        "elapsed_seconds": 0,
        "idle_seconds": 0,
        "iteration_current": 0,
        "iteration_max": 0,
        "last_activity_at": "2019-08-24T14:15:22Z",
        "last_activity_detail": "string",
        "last_activity_kind": "string",
        "last_progress_at": "2019-08-24T14:15:22Z",
        "tool_call_id": "string",
        "turn_id": "string",
        "turn_source": "string",
        "turn_started_at": "2019-08-24T14:15:22Z"
      },
      "agent_name": "string",
      "attach_expires_at": "2019-08-24T14:15:22Z",
      "attachable": true,
      "attached_to": "string",
      "badge": "string",
      "channel": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "failure": {
        "crash_bundle_path": "string",
        "kind": "string",
        "summary": "string"
      },
      "health": {
        "active_prompt": true,
        "agent_name": "string",
        "attachable": true,
        "eligible_for_wake": true,
        "health": "healthy",
        "ineligibility_reason": "session_prompt_active",
        "last_activity_at": "2019-08-24T14:15:22Z",
        "last_error": "string",
        "last_presence_at": "2019-08-24T14:15:22Z",
        "session_id": "string",
        "state": "idle",
        "updated_at": "2019-08-24T14:15:22Z",
        "workspace_id": "string"
      },
      "id": "string",
      "lineage": {
        "auto_stop_on_parent": true,
        "parent_session_id": "string",
        "permission_policy": {
          "mcp_servers": [
            "string"
          ],
          "network_channels": [
            "string"
          ],
          "sandbox_profiles": [
            "string"
          ],
          "skills": [
            "string"
          ],
          "tools": [
            "string"
          ],
          "workspace_paths": [
            "string"
          ]
        },
        "root_session_id": "string",
        "spawn_budget": {
          "max_active_per_workspace": 0,
          "max_children": 0,
          "max_depth": 0,
          "ttl_seconds": 0
        },
        "spawn_depth": 0,
        "spawn_role": "string",
        "ttl_expires_at": "2019-08-24T14:15:22Z"
      },
      "model": "string",
      "name": "string",
      "provider": "string",
      "reasoning_effort": "string",
      "sandbox": {
        "backend": "string",
        "instance_id": "string",
        "last_sync_error": "string",
        "profile": "string",
        "provider_state_json": null,
        "sandbox_id": "string",
        "state": "string"
      },
      "state": "starting",
      "stop_detail": "string",
      "stop_reason": "completed",
      "type": "user",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string",
      "workspace_path": "string"
    }
  ]
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Create a session

POST/api/sessions

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/sessions" \  -H "Content-Type: application/json" \  -d '{}'
{
  "session": {
    "acp_caps": {
      "config_options": [
        {
          "current": "string",
          "description": "string",
          "id": "string",
          "kind": "string",
          "label": "string",
          "values": [
            {
              "description": "string",
              "label": "string",
              "value": "string"
            }
          ]
        }
      ],
      "supported_models": [
        "string"
      ],
      "supported_modes": [
        "string"
      ],
      "supports_load_session": true
    },
    "acp_session_id": "string",
    "activity": {
      "current_tool": "string",
      "deadline_at": "2019-08-24T14:15:22Z",
      "elapsed_ms": 0,
      "elapsed_seconds": 0,
      "idle_seconds": 0,
      "iteration_current": 0,
      "iteration_max": 0,
      "last_activity_at": "2019-08-24T14:15:22Z",
      "last_activity_detail": "string",
      "last_activity_kind": "string",
      "last_progress_at": "2019-08-24T14:15:22Z",
      "tool_call_id": "string",
      "turn_id": "string",
      "turn_source": "string",
      "turn_started_at": "2019-08-24T14:15:22Z"
    },
    "agent_name": "string",
    "attach_expires_at": "2019-08-24T14:15:22Z",
    "attachable": true,
    "attached_to": "string",
    "badge": "string",
    "channel": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "failure": {
      "crash_bundle_path": "string",
      "kind": "string",
      "summary": "string"
    },
    "health": {
      "active_prompt": true,
      "agent_name": "string",
      "attachable": true,
      "eligible_for_wake": true,
      "health": "healthy",
      "ineligibility_reason": "session_prompt_active",
      "last_activity_at": "2019-08-24T14:15:22Z",
      "last_error": "string",
      "last_presence_at": "2019-08-24T14:15:22Z",
      "session_id": "string",
      "state": "idle",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string"
    },
    "id": "string",
    "lineage": {
      "auto_stop_on_parent": true,
      "parent_session_id": "string",
      "permission_policy": {
        "mcp_servers": [
          "string"
        ],
        "network_channels": [
          "string"
        ],
        "sandbox_profiles": [
          "string"
        ],
        "skills": [
          "string"
        ],
        "tools": [
          "string"
        ],
        "workspace_paths": [
          "string"
        ]
      },
      "root_session_id": "string",
      "spawn_budget": {
        "max_active_per_workspace": 0,
        "max_children": 0,
        "max_depth": 0,
        "ttl_seconds": 0
      },
      "spawn_depth": 0,
      "spawn_role": "string",
      "ttl_expires_at": "2019-08-24T14:15:22Z"
    },
    "model": "string",
    "name": "string",
    "provider": "string",
    "reasoning_effort": "string",
    "sandbox": {
      "backend": "string",
      "instance_id": "string",
      "last_sync_error": "string",
      "profile": "string",
      "provider_state_json": null,
      "sandbox_id": "string",
      "state": "string"
    },
    "state": "starting",
    "stop_detail": "string",
    "stop_reason": "completed",
    "type": "user",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string",
    "workspace_path": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Get one materialized Memory v2 session ledger

GET/api/workspaces/{workspace_id}/memory/sessions/{session_id}/ledger

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/memory/sessions/string/ledger"
{
  "events": [
    {
      "emitted_at": "2019-08-24T14:15:22Z",
      "event_type": "string",
      "payload": {
        "property1": null,
        "property2": null
      },
      "sequence": 0
    }
  ],
  "meta": {
    "checksum": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "parent_session_id": "string",
    "path": "string",
    "root_session_id": "string",
    "session_id": "string",
    "spawn_depth": 0,
    "stopped_at": "2019-08-24T14:15:22Z",
    "version": 0,
    "workspace_id": "string"
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Replay one materialized Memory v2 session ledger

POST/api/workspaces/{workspace_id}/memory/sessions/{session_id}/replay

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/memory/sessions/string/replay" \  -H "Content-Type: application/json" \  -d '{}'
{
  "events": [
    {
      "emitted_at": "2019-08-24T14:15:22Z",
      "event_type": "string",
      "payload": {
        "property1": null,
        "property2": null
      },
      "sequence": 0
    }
  ],
  "session_id": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Get one session snapshot

GET/api/workspaces/{workspace_id}/sessions/{session_id}

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

include_health?boolean

Include metadata-only session health when available

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/sessions/string"
{
  "session": {
    "acp_caps": {
      "config_options": [
        {
          "current": "string",
          "description": "string",
          "id": "string",
          "kind": "string",
          "label": "string",
          "values": [
            {
              "description": "string",
              "label": "string",
              "value": "string"
            }
          ]
        }
      ],
      "supported_models": [
        "string"
      ],
      "supported_modes": [
        "string"
      ],
      "supports_load_session": true
    },
    "acp_session_id": "string",
    "activity": {
      "current_tool": "string",
      "deadline_at": "2019-08-24T14:15:22Z",
      "elapsed_ms": 0,
      "elapsed_seconds": 0,
      "idle_seconds": 0,
      "iteration_current": 0,
      "iteration_max": 0,
      "last_activity_at": "2019-08-24T14:15:22Z",
      "last_activity_detail": "string",
      "last_activity_kind": "string",
      "last_progress_at": "2019-08-24T14:15:22Z",
      "tool_call_id": "string",
      "turn_id": "string",
      "turn_source": "string",
      "turn_started_at": "2019-08-24T14:15:22Z"
    },
    "agent_name": "string",
    "attach_expires_at": "2019-08-24T14:15:22Z",
    "attachable": true,
    "attached_to": "string",
    "badge": "string",
    "channel": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "failure": {
      "crash_bundle_path": "string",
      "kind": "string",
      "summary": "string"
    },
    "health": {
      "active_prompt": true,
      "agent_name": "string",
      "attachable": true,
      "eligible_for_wake": true,
      "health": "healthy",
      "ineligibility_reason": "session_prompt_active",
      "last_activity_at": "2019-08-24T14:15:22Z",
      "last_error": "string",
      "last_presence_at": "2019-08-24T14:15:22Z",
      "session_id": "string",
      "state": "idle",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string"
    },
    "id": "string",
    "lineage": {
      "auto_stop_on_parent": true,
      "parent_session_id": "string",
      "permission_policy": {
        "mcp_servers": [
          "string"
        ],
        "network_channels": [
          "string"
        ],
        "sandbox_profiles": [
          "string"
        ],
        "skills": [
          "string"
        ],
        "tools": [
          "string"
        ],
        "workspace_paths": [
          "string"
        ]
      },
      "root_session_id": "string",
      "spawn_budget": {
        "max_active_per_workspace": 0,
        "max_children": 0,
        "max_depth": 0,
        "ttl_seconds": 0
      },
      "spawn_depth": 0,
      "spawn_role": "string",
      "ttl_expires_at": "2019-08-24T14:15:22Z"
    },
    "model": "string",
    "name": "string",
    "provider": "string",
    "reasoning_effort": "string",
    "sandbox": {
      "backend": "string",
      "instance_id": "string",
      "last_sync_error": "string",
      "profile": "string",
      "provider_state_json": null,
      "sandbox_id": "string",
      "state": "string"
    },
    "state": "starting",
    "stop_detail": "string",
    "stop_reason": "completed",
    "type": "user",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string",
    "workspace_path": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Delete one session and remove it from persisted history

DELETE/api/workspaces/{workspace_id}/sessions/{session_id}

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

application/json

application/json

curl -X DELETE "https://example.com/api/workspaces/string/sessions/string"
Empty
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Approve or deny an interactive permission request

POST/api/workspaces/{workspace_id}/sessions/{session_id}/approve

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/sessions/string/approve" \  -H "Content-Type: application/json" \  -d '{    "decision": "string",    "request_id": "string",    "turn_id": "string"  }'
{
  "status": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Attach to a resumable live session

POST/api/workspaces/{workspace_id}/sessions/{session_id}/attach

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/sessions/string/attach" \  -H "Content-Type: application/json" \  -d '{}'
{
  "attach": {
    "attach_expires_at": "2019-08-24T14:15:22Z",
    "attached_at": "2019-08-24T14:15:22Z",
    "attached_to": "string",
    "session_id": "string"
  },
  "session": {
    "acp_caps": {
      "config_options": [
        {
          "current": "string",
          "description": "string",
          "id": "string",
          "kind": "string",
          "label": "string",
          "values": [
            {
              "description": "string",
              "label": "string",
              "value": "string"
            }
          ]
        }
      ],
      "supported_models": [
        "string"
      ],
      "supported_modes": [
        "string"
      ],
      "supports_load_session": true
    },
    "acp_session_id": "string",
    "activity": {
      "current_tool": "string",
      "deadline_at": "2019-08-24T14:15:22Z",
      "elapsed_ms": 0,
      "elapsed_seconds": 0,
      "idle_seconds": 0,
      "iteration_current": 0,
      "iteration_max": 0,
      "last_activity_at": "2019-08-24T14:15:22Z",
      "last_activity_detail": "string",
      "last_activity_kind": "string",
      "last_progress_at": "2019-08-24T14:15:22Z",
      "tool_call_id": "string",
      "turn_id": "string",
      "turn_source": "string",
      "turn_started_at": "2019-08-24T14:15:22Z"
    },
    "agent_name": "string",
    "attach_expires_at": "2019-08-24T14:15:22Z",
    "attachable": true,
    "attached_to": "string",
    "badge": "string",
    "channel": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "failure": {
      "crash_bundle_path": "string",
      "kind": "string",
      "summary": "string"
    },
    "health": {
      "active_prompt": true,
      "agent_name": "string",
      "attachable": true,
      "eligible_for_wake": true,
      "health": "healthy",
      "ineligibility_reason": "session_prompt_active",
      "last_activity_at": "2019-08-24T14:15:22Z",
      "last_error": "string",
      "last_presence_at": "2019-08-24T14:15:22Z",
      "session_id": "string",
      "state": "idle",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string"
    },
    "id": "string",
    "lineage": {
      "auto_stop_on_parent": true,
      "parent_session_id": "string",
      "permission_policy": {
        "mcp_servers": [
          "string"
        ],
        "network_channels": [
          "string"
        ],
        "sandbox_profiles": [
          "string"
        ],
        "skills": [
          "string"
        ],
        "tools": [
          "string"
        ],
        "workspace_paths": [
          "string"
        ]
      },
      "root_session_id": "string",
      "spawn_budget": {
        "max_active_per_workspace": 0,
        "max_children": 0,
        "max_depth": 0,
        "ttl_seconds": 0
      },
      "spawn_depth": 0,
      "spawn_role": "string",
      "ttl_expires_at": "2019-08-24T14:15:22Z"
    },
    "model": "string",
    "name": "string",
    "provider": "string",
    "reasoning_effort": "string",
    "sandbox": {
      "backend": "string",
      "instance_id": "string",
      "last_sync_error": "string",
      "profile": "string",
      "provider_state_json": null,
      "sandbox_id": "string",
      "state": "string"
    },
    "state": "starting",
    "stop_detail": "string",
    "stop_reason": "completed",
    "type": "user",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string",
    "workspace_path": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

List persisted session events

GET/api/workspaces/{workspace_id}/sessions/{session_id}/events

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

since?string

Only events emitted since this timestamp

Formatdate-time
limit?integer

Maximum number of records to return

Formatint32
after_sequence?integer

Only return events after this sequence number

Formatint64
type?string

Event type

agent_name?string

Agent name

turn_id?string

Turn id

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/sessions/string/events"
{
  "events": [
    {
      "actor_id": "string",
      "actor_kind": "string",
      "agent_name": "string",
      "claim_token_hash": "string",
      "content": null,
      "coordinator_session_id": "string",
      "failure": {
        "crash_bundle_path": "string",
        "kind": "string",
        "summary": "string"
      },
      "hook_event": "string",
      "hook_name": "string",
      "id": "string",
      "lease_until": "2019-08-24T14:15:22Z",
      "parent_session_id": "string",
      "release_reason": "string",
      "root_session_id": "string",
      "run_id": "string",
      "scheduler_reason": "string",
      "sequence": 0,
      "session_id": "string",
      "spawn_depth": 0,
      "stop_detail": "string",
      "stop_reason": "completed",
      "task_id": "string",
      "timestamp": "2019-08-24T14:15:22Z",
      "turn_id": "string",
      "type": "string",
      "workflow_id": "string",
      "workspace_id": "string",
      "workspace_path": "string"
    }
  ]
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Read metadata-only session health and wake eligibility

GET/api/workspaces/{workspace_id}/sessions/{session_id}/health

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/sessions/string/health"
{
  "health": {
    "active_prompt": true,
    "agent_name": "string",
    "attachable": true,
    "eligible_for_wake": true,
    "health": "healthy",
    "ineligibility_reason": "session_prompt_active",
    "last_activity_at": "2019-08-24T14:15:22Z",
    "last_error": "string",
    "last_presence_at": "2019-08-24T14:15:22Z",
    "session_id": "string",
    "state": "idle",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

List grouped session turn history

GET/api/workspaces/{workspace_id}/sessions/{session_id}/history

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

since?string

Only events emitted since this timestamp

Formatdate-time
limit?integer

Maximum number of records to return

Formatint32
after_sequence?integer

Only return events after this sequence number

Formatint64
type?string

Event type

agent_name?string

Agent name

turn_id?string

Turn id

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/sessions/string/history"
{
  "history": [
    {
      "events": [
        {
          "actor_id": "string",
          "actor_kind": "string",
          "agent_name": "string",
          "claim_token_hash": "string",
          "content": null,
          "coordinator_session_id": "string",
          "failure": {
            "crash_bundle_path": "string",
            "kind": "string",
            "summary": "string"
          },
          "hook_event": "string",
          "hook_name": "string",
          "id": "string",
          "lease_until": "2019-08-24T14:15:22Z",
          "parent_session_id": "string",
          "release_reason": "string",
          "root_session_id": "string",
          "run_id": "string",
          "scheduler_reason": "string",
          "sequence": 0,
          "session_id": "string",
          "spawn_depth": 0,
          "stop_detail": "string",
          "stop_reason": "completed",
          "task_id": "string",
          "timestamp": "2019-08-24T14:15:22Z",
          "turn_id": "string",
          "type": "string",
          "workflow_id": "string",
          "workspace_id": "string",
          "workspace_path": "string"
        }
      ],
      "turn_id": "string"
    }
  ]
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Inspect session health, wake audit, and policy correlation metadata

GET/api/workspaces/{workspace_id}/sessions/{session_id}/inspect

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

include_recent_wake_events?boolean

Include recent wake audit rows

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/sessions/string/inspect"
{
  "config_digest": "string",
  "diagnostics": [
    {
      "code": "string",
      "column": 0,
      "field": "string",
      "line": 0,
      "message": "string",
      "owner_surface": "string",
      "section": "string",
      "severity": "info",
      "source_path": "string"
    }
  ],
  "health": {
    "active_prompt": true,
    "agent_name": "string",
    "attachable": true,
    "eligible_for_wake": true,
    "health": "healthy",
    "ineligibility_reason": "session_prompt_active",
    "last_activity_at": "2019-08-24T14:15:22Z",
    "last_error": "string",
    "last_presence_at": "2019-08-24T14:15:22Z",
    "session_id": "string",
    "state": "idle",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string"
  },
  "policy_digest": "string",
  "session_id": "string",
  "wake_events": [
    {
      "agent_name": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "id": "string",
      "policy_snapshot_id": "string",
      "reason": "wake_sent",
      "result": "sent",
      "session_id": "string",
      "source": "scheduler",
      "synthetic_prompt_id": "string",
      "workspace_id": "string"
    }
  ],
  "wake_state": {
    "agent_name": "string",
    "coalesced_count": 0,
    "last_reason": "wake_sent",
    "last_result": "sent",
    "last_wake_at": "2019-08-24T14:15:22Z",
    "next_allowed_at": "2019-08-24T14:15:22Z",
    "policy_snapshot_id": "string",
    "session_id": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Interrupt the active prompt turn for a session

POST/api/workspaces/{workspace_id}/sessions/{session_id}/interrupt

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/sessions/string/interrupt"
{
  "prompt": {
    "canceled_queued_entries": 0,
    "estimated_send_at": "2019-08-24T14:15:22Z",
    "fallback_mode_if_no_tool_result": "string",
    "interrupted": true,
    "mode": "string",
    "new_turn_id": "string",
    "previous_turn_id": "string",
    "queue_entry_id": "string",
    "queue_generation": 0,
    "queue_position": 0,
    "queued": true,
    "staged": true,
    "status": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Send, queue, interrupt, or steer a session prompt

POST/api/workspaces/{workspace_id}/sessions/{session_id}/prompt

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/sessions/string/prompt" \  -H "Content-Type: application/json" \  -d '{}'
{
  "prompt": {
    "canceled_queued_entries": 0,
    "estimated_send_at": "2019-08-24T14:15:22Z",
    "fallback_mode_if_no_tool_result": "string",
    "interrupted": true,
    "mode": "string",
    "new_turn_id": "string",
    "previous_turn_id": "string",
    "queue_entry_id": "string",
    "queue_generation": 0,
    "queue_position": 0,
    "queued": true,
    "staged": true,
    "status": "string"
  }
}
{
  "prompt": {
    "canceled_queued_entries": 0,
    "estimated_send_at": "2019-08-24T14:15:22Z",
    "fallback_mode_if_no_tool_result": "string",
    "interrupted": true,
    "mode": "string",
    "new_turn_id": "string",
    "previous_turn_id": "string",
    "queue_entry_id": "string",
    "queue_generation": 0,
    "queue_position": 0,
    "queued": true,
    "staged": true,
    "status": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Cancel a queued session prompt entry

DELETE/api/workspaces/{workspace_id}/sessions/{session_id}/prompt/queue/{queue_entry_id}

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

queue_entry_id*string

Queue entry id

Response Body

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/workspaces/string/sessions/string/prompt/queue/string"
{
  "prompt": {
    "canceled_queued_entries": 0,
    "estimated_send_at": "2019-08-24T14:15:22Z",
    "fallback_mode_if_no_tool_result": "string",
    "interrupted": true,
    "mode": "string",
    "new_turn_id": "string",
    "previous_turn_id": "string",
    "queue_entry_id": "string",
    "queue_generation": 0,
    "queue_position": 0,
    "queued": true,
    "staged": true,
    "status": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Get a deterministic session recap

GET/api/workspaces/{workspace_id}/sessions/{session_id}/recap

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

limit?integer

Maximum recent messages to include

Formatint32

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/sessions/string/recap"
{
  "recap": {
    "active_run": {
      "attempt": 0,
      "claim_token_hash": "string",
      "claimed_at": "2019-08-24T14:15:22Z",
      "claimed_by": {
        "kind": "human",
        "ref": "string"
      },
      "coordination_channel": {
        "allowed_message_kinds": [
          "status"
        ],
        "channel": "string",
        "display_name": "string",
        "id": "string",
        "last_activity_at": "2019-08-24T14:15:22Z",
        "purpose": "string",
        "run_id": "string",
        "task_id": "string",
        "workflow_id": "string",
        "workspace_id": "string"
      },
      "coordination_channel_id": "string",
      "ended_at": "2019-08-24T14:15:22Z",
      "error": "string",
      "failure_kind": "string",
      "heartbeat_at": "2019-08-24T14:15:22Z",
      "id": "string",
      "idempotency_key": "string",
      "lease_until": "2019-08-24T14:15:22Z",
      "metadata": null,
      "network_channel": "string",
      "origin": {
        "kind": "cli",
        "ref": "string"
      },
      "previous_run_id": "string",
      "queued_at": "2019-08-24T14:15:22Z",
      "result": null,
      "session_id": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "status": "queued",
      "task_id": "string"
    },
    "pending_inputs": 0,
    "pending_markers": 0,
    "recent_markers": [
      {
        "diagnostic": null,
        "evidence": {
          "property1": null,
          "property2": null
        },
        "kind": "string",
        "occurred_at": "2019-08-24T14:15:22Z",
        "summary": "string"
      }
    ],
    "recent_messages": [
      {
        "id": "string",
        "metadata": null,
        "parts": [
          {
            "data": null,
            "errorText": "string",
            "id": "string",
            "input": null,
            "output": null,
            "preliminary": true,
            "rawInput": null,
            "state": "string",
            "text": "string",
            "title": "string",
            "toolCallId": "string",
            "toolName": "string",
            "type": "string"
          }
        ],
        "role": "string"
      }
    ],
    "session": {
      "acp_caps": {
        "config_options": [
          {
            "current": "string",
            "description": "string",
            "id": "string",
            "kind": "string",
            "label": "string",
            "values": [
              {
                "description": "string",
                "label": "string",
                "value": "string"
              }
            ]
          }
        ],
        "supported_models": [
          "string"
        ],
        "supported_modes": [
          "string"
        ],
        "supports_load_session": true
      },
      "acp_session_id": "string",
      "activity": {
        "current_tool": "string",
        "deadline_at": "2019-08-24T14:15:22Z",
        "elapsed_ms": 0,
        "elapsed_seconds": 0,
        "idle_seconds": 0,
        "iteration_current": 0,
        "iteration_max": 0,
        "last_activity_at": "2019-08-24T14:15:22Z",
        "last_activity_detail": "string",
        "last_activity_kind": "string",
        "last_progress_at": "2019-08-24T14:15:22Z",
        "tool_call_id": "string",
        "turn_id": "string",
        "turn_source": "string",
        "turn_started_at": "2019-08-24T14:15:22Z"
      },
      "agent_name": "string",
      "attach_expires_at": "2019-08-24T14:15:22Z",
      "attachable": true,
      "attached_to": "string",
      "badge": "string",
      "channel": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "failure": {
        "crash_bundle_path": "string",
        "kind": "string",
        "summary": "string"
      },
      "health": {
        "active_prompt": true,
        "agent_name": "string",
        "attachable": true,
        "eligible_for_wake": true,
        "health": "healthy",
        "ineligibility_reason": "session_prompt_active",
        "last_activity_at": "2019-08-24T14:15:22Z",
        "last_error": "string",
        "last_presence_at": "2019-08-24T14:15:22Z",
        "session_id": "string",
        "state": "idle",
        "updated_at": "2019-08-24T14:15:22Z",
        "workspace_id": "string"
      },
      "id": "string",
      "lineage": {
        "auto_stop_on_parent": true,
        "parent_session_id": "string",
        "permission_policy": {
          "mcp_servers": [
            "string"
          ],
          "network_channels": [
            "string"
          ],
          "sandbox_profiles": [
            "string"
          ],
          "skills": [
            "string"
          ],
          "tools": [
            "string"
          ],
          "workspace_paths": [
            "string"
          ]
        },
        "root_session_id": "string",
        "spawn_budget": {
          "max_active_per_workspace": 0,
          "max_children": 0,
          "max_depth": 0,
          "ttl_seconds": 0
        },
        "spawn_depth": 0,
        "spawn_role": "string",
        "ttl_expires_at": "2019-08-24T14:15:22Z"
      },
      "model": "string",
      "name": "string",
      "provider": "string",
      "reasoning_effort": "string",
      "sandbox": {
        "backend": "string",
        "instance_id": "string",
        "last_sync_error": "string",
        "profile": "string",
        "provider_state_json": null,
        "sandbox_id": "string",
        "state": "string"
      },
      "state": "starting",
      "stop_detail": "string",
      "stop_reason": "completed",
      "type": "user",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string",
      "workspace_path": "string"
    },
    "snapshot": {
      "consistency": "string",
      "event_cursor": 0,
      "generated_at": "2019-08-24T14:15:22Z",
      "queue_generation": 0,
      "transcript_cursor": 0
    }
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Inspect and repair an interrupted session transcript

POST/api/workspaces/{workspace_id}/sessions/{session_id}/repair

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

dry_run?boolean

Report planned repairs without persisting new events

force?boolean

Allow repair for stopped sessions whose stop reason is not crash or error

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/sessions/string/repair"
{
  "repair": {
    "actions": [
      {
        "code": "string",
        "event_id": "string",
        "persisted": true,
        "tool_call_id": "string",
        "tool_name": "string",
        "turn_id": "string"
      }
    ],
    "issues": [
      {
        "code": "string",
        "detail": "string",
        "event_id": "string",
        "severity": "string",
        "turn_id": "string"
      }
    ],
    "persisted": true,
    "session_id": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Refresh an idle session's Soul snapshot through body-level CAS

POST/api/workspaces/{workspace_id}/sessions/{session_id}/soul/refresh

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/sessions/string/soul/refresh" \  -H "Content-Type: application/json" \  -d '{    "expected_digest": "string"  }'
{
  "active": true,
  "agent_name": "string",
  "body": "string",
  "config_provenance": {
    "context_projection_bytes": 0,
    "digest": "string",
    "enabled": true,
    "max_body_bytes": 0,
    "source": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "diagnostics": [
    {
      "code": "string",
      "column": 0,
      "field": "string",
      "line": 0,
      "message": "string",
      "owner_surface": "string",
      "section": "string",
      "severity": "info",
      "source_path": "string"
    }
  ],
  "digest": "string",
  "enabled": true,
  "frontmatter": {
    "collaboration": [
      "string"
    ],
    "constraints": [
      "string"
    ],
    "memory_policy": [
      "string"
    ],
    "principles": [
      "string"
    ],
    "role": "string",
    "tags": [
      "string"
    ],
    "tone": [
      "string"
    ],
    "version": "string"
  },
  "limits": {
    "context_projection_bytes": 0,
    "max_body_bytes": 0,
    "max_bytes": 0
  },
  "present": true,
  "revision_id": "string",
  "snapshot_id": "string",
  "source_path": "string",
  "truncated": true,
  "valid": true,
  "validation_status": "missing"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "active": true,
  "agent_name": "string",
  "body": "string",
  "config_provenance": {
    "context_projection_bytes": 0,
    "digest": "string",
    "enabled": true,
    "max_body_bytes": 0,
    "source": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "diagnostics": [
    {
      "code": "string",
      "column": 0,
      "field": "string",
      "line": 0,
      "message": "string",
      "owner_surface": "string",
      "section": "string",
      "severity": "info",
      "source_path": "string"
    }
  ],
  "digest": "string",
  "enabled": true,
  "frontmatter": {
    "collaboration": [
      "string"
    ],
    "constraints": [
      "string"
    ],
    "memory_policy": [
      "string"
    ],
    "principles": [
      "string"
    ],
    "role": "string",
    "tags": [
      "string"
    ],
    "tone": [
      "string"
    ],
    "version": "string"
  },
  "limits": {
    "context_projection_bytes": 0,
    "max_body_bytes": 0,
    "max_bytes": 0
  },
  "present": true,
  "revision_id": "string",
  "snapshot_id": "string",
  "source_path": "string",
  "truncated": true,
  "valid": true,
  "validation_status": "missing"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Read compact session status and wake eligibility

GET/api/workspaces/{workspace_id}/sessions/{session_id}/status

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/sessions/string/status"
{
  "active_prompt": true,
  "agent_name": "string",
  "attachable": true,
  "eligible_for_wake": true,
  "health": "healthy",
  "ineligibility_reason": "session_prompt_active",
  "session_id": "string",
  "state": "idle",
  "updated_at": "2019-08-24T14:15:22Z",
  "wake_state": {
    "agent_name": "string",
    "coalesced_count": 0,
    "last_reason": "wake_sent",
    "last_result": "sent",
    "last_wake_at": "2019-08-24T14:15:22Z",
    "next_allowed_at": "2019-08-24T14:15:22Z",
    "policy_snapshot_id": "string",
    "session_id": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string"
  },
  "workspace_id": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Stage steering input for the active session turn

POST/api/workspaces/{workspace_id}/sessions/{session_id}/steer

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

text*string

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/sessions/string/steer" \  -H "Content-Type: application/json" \  -d '{    "text": "string"  }'
{
  "prompt": {
    "canceled_queued_entries": 0,
    "estimated_send_at": "2019-08-24T14:15:22Z",
    "fallback_mode_if_no_tool_result": "string",
    "interrupted": true,
    "mode": "string",
    "new_turn_id": "string",
    "previous_turn_id": "string",
    "queue_entry_id": "string",
    "queue_generation": 0,
    "queue_position": 0,
    "queued": true,
    "staged": true,
    "status": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Stop a session without deleting persisted history

POST/api/workspaces/{workspace_id}/sessions/{session_id}/stop

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/sessions/string/stop"
Empty
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

List session-callable registry tools

GET/api/workspaces/{workspace_id}/sessions/{session_id}/tools

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

agent_name?string

Effective agent name

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/sessions/string/tools"
{
  "tools": [
    {
      "availability": {
        "authorized": true,
        "available": true,
        "conflicted": true,
        "enabled": true,
        "executable": true,
        "reason_codes": [
          "approval_canceled"
        ],
        "registered": true
      },
      "decision": {
        "agent_policy_result": "string",
        "approval_required": true,
        "availability_result": "string",
        "callable": true,
        "hook_result": "string",
        "reason_codes": [
          "approval_canceled"
        ],
        "registry_policy_result": "string",
        "session_policy_result": "string",
        "source_policy_result": "string",
        "system_permission_mode": "string",
        "visible_to_operator": true,
        "visible_to_session": true
      },
      "descriptor": {
        "backend": {
          "extension_id": "string",
          "handler": "string",
          "kind": "native_go",
          "mcp_server": "string",
          "mcp_tool": "string",
          "native_name": "string",
          "requires_capabilities": [
            "string"
          ]
        },
        "concurrency_safe": true,
        "description": "string",
        "destructive": true,
        "display_title": "string",
        "input_schema": null,
        "input_schema_digest": "string",
        "max_result_bytes": 0,
        "open_world": true,
        "output_schema": null,
        "output_schema_digest": "string",
        "read_only": true,
        "requires_interaction": true,
        "risk": "read",
        "search_hints": [
          "string"
        ],
        "source": {
          "kind": "builtin",
          "owner": "string",
          "raw_server_name": "string",
          "raw_tool_name": "string",
          "resource_id": "string",
          "resource_version": "string",
          "scope": "string",
          "workspace_id": "string"
        },
        "tags": [
          "string"
        ],
        "tool_id": "string",
        "toolsets": [
          "string"
        ],
        "visibility": "internal"
      }
    }
  ]
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Search session-callable registry tools

POST/api/workspaces/{workspace_id}/sessions/{session_id}/tools/search

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/sessions/string/tools/search" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{
  "tools": [
    {
      "availability": {
        "authorized": true,
        "available": true,
        "conflicted": true,
        "enabled": true,
        "executable": true,
        "reason_codes": [
          "approval_canceled"
        ],
        "registered": true
      },
      "decision": {
        "agent_policy_result": "string",
        "approval_required": true,
        "availability_result": "string",
        "callable": true,
        "hook_result": "string",
        "reason_codes": [
          "approval_canceled"
        ],
        "registry_policy_result": "string",
        "session_policy_result": "string",
        "source_policy_result": "string",
        "system_permission_mode": "string",
        "visible_to_operator": true,
        "visible_to_session": true
      },
      "descriptor": {
        "backend": {
          "extension_id": "string",
          "handler": "string",
          "kind": "native_go",
          "mcp_server": "string",
          "mcp_tool": "string",
          "native_name": "string",
          "requires_capabilities": [
            "string"
          ]
        },
        "concurrency_safe": true,
        "description": "string",
        "destructive": true,
        "display_title": "string",
        "input_schema": null,
        "input_schema_digest": "string",
        "max_result_bytes": 0,
        "open_world": true,
        "output_schema": null,
        "output_schema_digest": "string",
        "read_only": true,
        "requires_interaction": true,
        "risk": "read",
        "search_hints": [
          "string"
        ],
        "source": {
          "kind": "builtin",
          "owner": "string",
          "raw_server_name": "string",
          "raw_tool_name": "string",
          "resource_id": "string",
          "resource_version": "string",
          "scope": "string",
          "workspace_id": "string"
        },
        "tags": [
          "string"
        ],
        "tool_id": "string",
        "toolsets": [
          "string"
        ],
        "visibility": "internal"
      }
    }
  ]
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "error": {
    "code": "tool_not_found",
    "details": {
      "property1": null,
      "property2": null
    },
    "layer": "string",
    "message": "string",
    "reason_codes": [
      "approval_canceled"
    ],
    "tool_id": "string"
  }
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

Get the canonical transcript for one session

GET/api/workspaces/{workspace_id}/sessions/{session_id}/transcript

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/sessions/string/transcript"
{
  "messages": [
    {
      "id": "string",
      "metadata": null,
      "parts": [
        {
          "data": null,
          "errorText": "string",
          "id": "string",
          "input": null,
          "output": null,
          "preliminary": true,
          "rawInput": null,
          "state": "string",
          "text": "string",
          "title": "string",
          "toolCallId": "string",
          "toolName": "string",
          "type": "string"
        }
      ],
      "role": "string"
    }
  ]
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
{
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string"
}
Empty

API Reference

Per-tag HTTP and SSE reference for the AGH daemon, generated from the canonical OpenAPI contract on every site build.

Workspaces

AGH Workspaces HTTP endpoints.