Manage workspaces

Create, configure and delete workspaces with the same URLs the web app uses.

Endpoints

• Every current route selects its workspace with X-Space-Slug.
• Manage workspace settings (workspace:manage_settings) is Admin-only by default; a Member's key gets 403 You do not have permission to perform 'manage_settings' on 'workspace'.
• Which key reaches which route: Authentication and API keys. The examples use $ALO_API_KEY for a workspace key and $ALO_PLATFORM_API_KEY for a platform key.

Create a workspace

Works with: a signed-in user or a platform key. A workspace key gets 403.

1. Optional: find agent IDs for the new workspace. Manufacturing, Finance and Pharma agents are global agents tagged manufacturing, finance and pharma:

   curl "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/?show_platform=true&tag_in=manufacturing" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG"

2. Create the workspace. name is the only required field; the server generates the slug.

   curl -X POST "$CENTRAL_HUB_URL/api/v1/spaces/" \
     -H "X-API-Key: $ALO_PLATFORM_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name": "Manufacturing Operations"}'

   The response is 201 with the workspace; use its slug as X-Space-Slug from now on:

   {
     "id": 282,
     "slug": "manufacturing-operations",
     "name": "Manufacturing Operations",
     "status": "active",
     "is_default": false,
     "created_by_id": 1,
     "updated_by_id": 1,
     "created_at": "2026-10-13T19:22:21.942657Z",
     "updated_at": "2026-10-13T19:22:21.942660Z",
     "role_slug": "admin",
     "role_name": null,
     "organization_id": null,
     "is_creator": true,
     "created_by_email": null,
     "member_count": 0,
     "is_shared": false
   }

   The create response does not count members (member_count: 0); the creator is the workspace's Admin, which a later GET /api/v1/spaces/current/ shows.

3. To set the default agent and landing suggestions in the same call, add initial_settings with the settings fields:

   {
     "name": "Manufacturing Operations",
     "initial_settings": {
       "default_agent_id": 42,
       "landing_suggestions": [
         {"agent_id": 42, "label": "Review OEE", "prompt": "Analyze manufacturing OEE and recommend improvements.", "icon": "factory"}
       ]
     }
   }

• Creation is atomic: the workspace, default roles, your membership, required agents, settings and suggestions are created together.
• An unknown or unavailable agent ID returns 422 Unknown or unavailable agent ID and creates nothing. Unknown or disabled model IDs are dropped without an error.
• Global agents referenced by the default agent or a suggestion are installed automatically.
• 403 Missing capability system:create_workspace: the caller's account may not create workspaces.
• 403 Your role does not allow creating workspaces or 403 You have reached your role's workspace limit (n): the caller's organization role caps the workspaces they create in the organization.
• 422 You are not a member of an organization: in_organization is true but the caller has no organization. Platform admins place a workspace in any organization with POST /api/v1/platform-admin/spaces/.

Install an agent

Requires: Manage workspace settings (Admin by default).

1. Find the agent: GET /api/v1/agents-v2/agents/?show_platform=true lists the whole catalog with an installed flag.

2. Install it:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/42/add-to-space/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG"

3. To remove it, send DELETE to the same URL.

• Only installed agents appear in the workspace's agent lists.
• Removing a required agent, the default agent or one used by an active suggestion returns 422.
• Settings may reference only workspace-owned or installed agents.

Rename the workspace and edit settings

Requires: Manage workspace settings (Admin by default).

1. Rename it:

   curl -X PATCH "$CENTRAL_HUB_URL/api/v1/spaces/current/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"name": "Manufacturing Ops"}'

2. Edit settings. Send only the fields you change:

   curl -X PATCH "$CENTRAL_HUB_URL/api/v1/spaces/current/settings/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"landing_suggestions": []}'

Settings fields

A landing suggestion requires agent_id, label (1–48 characters, at most three words) and prompt (up to 4,000 characters); active defaults to true, icon to bot, and categories holds at most 8.

Delete the workspace

Requires: the workspace's creator. Platform admins delete any workspace with DELETE /api/v1/platform-admin/spaces/{slug}/.

Deleting is permanent: the workspace's agents, connections, files, settings and API keys are deleted with it.

1. Confirm with a person before deleting a review or QA workspace.

2. Delete it:

   curl -X DELETE "$CENTRAL_HUB_URL/api/v1/spaces/current/" \
     -H "X-API-Key: $ALO_PLATFORM_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG"

3. Verify: the call returns 204. The workspace's own keys stop working (401); with another credential, GET /api/v1/spaces/current/ returns 404.