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://loading/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": {
        "supported_models": [
          "string"
        ],
        "supported_modes": [
          "string"
        ],
        "supports_load_session": true
      },
      "acp_session_id": "string",
      "activity": {
        "current_tool": "string",
        "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",
      "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"
      },
      "name": "string",
      "provider": "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": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string",
      "workspace_path": "string"
    }
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "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

Response Body

application/json

application/json

application/json

curl -X GET "https://loading/api/sessions"
{
  "sessions": [
    {
      "acp_caps": {
        "supported_models": [
          "string"
        ],
        "supported_modes": [
          "string"
        ],
        "supports_load_session": true
      },
      "acp_session_id": "string",
      "activity": {
        "current_tool": "string",
        "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",
      "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"
      },
      "name": "string",
      "provider": "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": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string",
      "workspace_path": "string"
    }
  ]
}
{
  "error": "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://loading/api/sessions" \  -H "Content-Type: application/json" \  -d '{}'
{
  "session": {
    "acp_caps": {
      "supported_models": [
        "string"
      ],
      "supported_modes": [
        "string"
      ],
      "supports_load_session": true
    },
    "acp_session_id": "string",
    "activity": {
      "current_tool": "string",
      "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",
    "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"
    },
    "name": "string",
    "provider": "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": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string",
    "workspace_path": "string"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Get one session snapshot

GET/api/sessions/{id}

Path Parameters

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://loading/api/sessions/string"
{
  "session": {
    "acp_caps": {
      "supported_models": [
        "string"
      ],
      "supported_modes": [
        "string"
      ],
      "supports_load_session": true
    },
    "acp_session_id": "string",
    "activity": {
      "current_tool": "string",
      "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",
    "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"
    },
    "name": "string",
    "provider": "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": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string",
    "workspace_path": "string"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Delete one session and remove it from persisted history

DELETE/api/sessions/{id}

Path Parameters

id*string

Session id

Response Body

application/json

application/json

curl -X DELETE "https://loading/api/sessions/string"
Empty
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Approve or deny an interactive permission request

POST/api/sessions/{id}/approve

Path Parameters

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://loading/api/sessions/string/approve" \  -H "Content-Type: application/json" \  -d '{    "decision": "string",    "request_id": "string",    "turn_id": "string"  }'
{
  "status": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

List persisted session events

GET/api/sessions/{id}/events

Path Parameters

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://loading/api/sessions/string/events"
{
  "events": [
    {
      "agent_name": "string",
      "content": null,
      "failure": {
        "crash_bundle_path": "string",
        "kind": "string",
        "summary": "string"
      },
      "id": "string",
      "sequence": 0,
      "session_id": "string",
      "stop_detail": "string",
      "stop_reason": "completed",
      "timestamp": "2019-08-24T14:15:22Z",
      "turn_id": "string",
      "type": "string",
      "workspace_id": "string",
      "workspace_path": "string"
    }
  ]
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

List grouped session turn history

GET/api/sessions/{id}/history

Path Parameters

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://loading/api/sessions/string/history"
{
  "history": [
    {
      "events": [
        {
          "agent_name": "string",
          "content": null,
          "failure": {
            "crash_bundle_path": "string",
            "kind": "string",
            "summary": "string"
          },
          "id": "string",
          "sequence": 0,
          "session_id": "string",
          "stop_detail": "string",
          "stop_reason": "completed",
          "timestamp": "2019-08-24T14:15:22Z",
          "turn_id": "string",
          "type": "string",
          "workspace_id": "string",
          "workspace_path": "string"
        }
      ],
      "turn_id": "string"
    }
  ]
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Inspect and repair an interrupted session transcript

POST/api/sessions/{id}/repair

Path Parameters

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://loading/api/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"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Resume a stopped session

POST/api/sessions/{id}/resume

Path Parameters

id*string

Session id

Response Body

application/json

application/json

application/json

curl -X POST "https://loading/api/sessions/string/resume"
{
  "session": {
    "acp_caps": {
      "supported_models": [
        "string"
      ],
      "supported_modes": [
        "string"
      ],
      "supports_load_session": true
    },
    "acp_session_id": "string",
    "activity": {
      "current_tool": "string",
      "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",
    "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"
    },
    "name": "string",
    "provider": "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": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string",
    "workspace_path": "string"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Stop a session without deleting persisted history

POST/api/sessions/{id}/stop

Path Parameters

id*string

Session id

Response Body

application/json

application/json

curl -X POST "https://loading/api/sessions/string/stop"
Empty
{
  "error": "string"
}
{
  "error": "string"
}
Empty

List session-callable registry tools

GET/api/sessions/{id}/tools

Path Parameters

id*string

Session id

Query Parameters

workspace_id?string

Effective workspace id

workspace?string

Effective workspace reference

agent_name?string

Effective agent name

Response Body

application/json

application/json

application/json

curl -X GET "https://loading/api/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,
        "max_result_bytes": 0,
        "open_world": true,
        "output_schema": null,
        "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": "string"
}
Empty

Search session-callable registry tools

POST/api/sessions/{id}/tools/search

Path Parameters

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://loading/api/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,
        "max_result_bytes": 0,
        "open_world": true,
        "output_schema": null,
        "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"
  }
}
{
  "error": "string"
}
Empty

Get the canonical transcript for one session

GET/api/sessions/{id}/transcript

Path Parameters

id*string

Session id

Response Body

application/json

application/json

application/json

curl -X GET "https://loading/api/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"
    }
  ]
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Read metadata-only session health and wake eligibility

GET/api/sessions/{session_id}/health

Path Parameters

session_id*string

Session id

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/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"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Inspect session health, wake audit, and policy correlation metadata

GET/api/sessions/{session_id}/inspect

Path Parameters

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://loading/api/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"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

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

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

Path Parameters

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://loading/api/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"
}
{
  "error": "string"
}
{
  "error": "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"
}
{
  "error": "string"
}
Empty

Read compact session status and wake eligibility

GET/api/sessions/{session_id}/status

Path Parameters

session_id*string

Session id

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/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"
}
{
  "error": "string"
}
{
  "error": "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.