Skip to content
Core ConceptsCLI ReferenceAPI Reference
AGH RuntimeAPI Reference

Workspaces

AGH Workspaces HTTP endpoints.

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

List registered workspaces

GET/api/workspaces

Response Body

application/json

application/json

curl -X GET "https://loading/api/workspaces"
{
  "workspaces": [
    {
      "add_dirs": [
        "string"
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "default_agent": "string",
      "id": "string",
      "name": "string",
      "root_dir": "string",
      "sandbox_ref": "string",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}
{
  "error": "string"
}
Empty

Register a workspace

POST/api/workspaces

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/workspaces" \  -H "Content-Type: application/json" \  -d '{    "root_dir": "string"  }'
{
  "workspace": {
    "add_dirs": [
      "string"
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "default_agent": "string",
    "id": "string",
    "name": "string",
    "root_dir": "string",
    "sandbox_ref": "string",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Resolve or register a workspace from a path

POST/api/workspaces/resolve

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

path*string

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/workspaces/resolve" \  -H "Content-Type: application/json" \  -d '{    "path": "string"  }'
{
  "workspace": {
    "add_dirs": [
      "string"
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "default_agent": "string",
    "id": "string",
    "name": "string",
    "root_dir": "string",
    "sandbox_ref": "string",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty
GET/api/workspaces/{id}

Path Parameters

id*string

Workspace id or path

Response Body

application/json

application/json

application/json

curl -X GET "https://loading/api/workspaces/string"
{
  "agents": [
    {
      "command": "string",
      "deny_tools": [
        "string"
      ],
      "mcp_servers": [
        {
          "args": [
            "string"
          ],
          "auth": {
            "authorization_url": "string",
            "client_id": "string",
            "client_secret_ref": "string",
            "issuer_url": "string",
            "metadata_url": "string",
            "revocation_url": "string",
            "scopes": [
              "string"
            ],
            "token_url": "string",
            "type": "string"
          },
          "command": "string",
          "env": {
            "property1": "string",
            "property2": "string"
          },
          "name": "string",
          "secret_env": {
            "property1": "string",
            "property2": "string"
          },
          "transport": "string",
          "url": "string"
        }
      ],
      "model": "string",
      "name": "string",
      "permissions": "string",
      "prompt": "string",
      "provider": "string",
      "tools": [
        "string"
      ],
      "toolsets": [
        "string"
      ]
    }
  ],
  "providers": [
    {
      "default_model": "string",
      "display_name": "string",
      "harness": "string",
      "name": "string",
      "runtime_provider": "string"
    }
  ],
  "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"
    }
  ],
  "skills": [
    {
      "dir": "string",
      "name": "string",
      "source": "string"
    }
  ],
  "workspace": {
    "add_dirs": [
      "string"
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "default_agent": "string",
    "id": "string",
    "name": "string",
    "root_dir": "string",
    "sandbox_ref": "string",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Update a registered workspace

PATCH/api/workspaces/{id}

Path Parameters

id*string

Workspace 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 PATCH "https://loading/api/workspaces/string" \  -H "Content-Type: application/json" \  -d '{    "add_dirs": [      "string"    ],    "default_agent": "string",    "name": "string",    "sandbox_ref": "string"  }'
{
  "workspace": {
    "add_dirs": [
      "string"
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "default_agent": "string",
    "id": "string",
    "name": "string",
    "root_dir": "string",
    "sandbox_ref": "string",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Delete a registered workspace

DELETE/api/workspaces/{id}

Path Parameters

id*string

Workspace id

Response Body

application/json

application/json

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

Sessions

AGH Sessions HTTP endpoints.

Agents

AGH Agents HTTP endpoints.