> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Manage workspaces

Manage workspaces [#manage-workspaces]

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

Endpoints [#endpoints]

| Method            | URL                                                 | Does                                                   | Requires                               | Auth                   |
| ----------------- | --------------------------------------------------- | ------------------------------------------------------ | -------------------------------------- | ---------------------- |
| `GET`             | `/api/v1/spaces/`                                   | The workspaces the key's owner belongs to              | Any member                             | Key or bearer          |
| `POST`            | `/api/v1/spaces/`                                   | Create a workspace, optionally with `initial_settings` | Allowed to create workspaces           | Platform key or bearer |
| `GET`             | `/api/v1/spaces/current/`                           | Read the workspace                                     | Any member                             | Key or bearer          |
| `PATCH`           | `/api/v1/spaces/current/`                           | Rename it                                              | Manage workspace settings              | Key or bearer          |
| `DELETE`          | `/api/v1/spaces/current/`                           | Delete it                                              | The workspace's creator                | Key or bearer          |
| `GET` · `PATCH`   | `/api/v1/spaces/current/settings/`                  | Read · edit settings and landing suggestions           | Any member · Manage workspace settings | Key or bearer          |
| `POST` · `DELETE` | `/api/v1/agents-v2/agents/{agent_id}/add-to-space/` | Install · remove an optional global agent              | Manage workspace settings              | Key or bearer          |
| `GET`             | `/api/v1/platform-admin/spaces/`                    | List all workspaces (`search`, `page`, `page_size`)    | Platform admin                         | Platform key or bearer |
| `DELETE`          | `/api/v1/platform-admin/spaces/{slug}/`             | Delete any workspace                                   | Platform admin                         | Platform key or bearer |

* 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](../api-basics/authentication). The examples use `$ALO_API_KEY` for a workspace key and `$ALO_PLATFORM_API_KEY` for a platform key.

Create a workspace [#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`:

   ```bash
   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`.

   ```bash
   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:

   ```json
   {
     "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](#settings-fields):

   ```json
   {
     "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"}
       ]
     }
   }
   ```

| Field              | Type                     | Notes                                                                                                                                  |
| ------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | string, required         | 1–255 characters                                                                                                                       |
| `initial_settings` | object                   | Same fields as [settings](#settings-fields)                                                                                            |
| `organization_id`  | UUID                     | Creates the workspace in that organization; you must be a member of it, home or external, else `403`                                   |
| `in_organization`  | boolean, default `false` | Without `organization_id`, a home member's workspace always goes into their home organization. `true` without an organization is `422` |

* 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](../platform/organizations#organization-roles) 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/`](./set-up-a-client).

Install an agent [#install-an-agent]

Requires: Manage workspace settings (Admin by default).

| Agent                           | In the workspace          |
| ------------------------------- | ------------------------- |
| Alo, App Builder, Agent Builder | Always; cannot be removed |
| Other global agents             | Only after `add-to-space` |
| Workspace-owned agents          | Always                    |

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

2. Install it:

   ```bash
   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 [#rename-the-workspace-and-edit-settings]

Requires: Manage workspace settings (Admin by default).

1. Rename it:

   ```bash
   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:

   ```bash
   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 [#settings-fields]

| Field                 | Type                          | Notes                                                                                             |
| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `default_agent_id`    | integer or `null`             | A workspace-owned or installed agent                                                              |
| `landing_suggestions` | array or `null`               | Replaces the whole list; `[]` removes the workspace's own list and restores the platform defaults |
| `enabled_model_ids`   | array or `null`               | `null` = every model allowed; `[]` = no model allowed; unknown or disabled IDs are dropped        |
| `landing_text_color`  | `dark` or `light`             | Default `dark`                                                                                    |
| `agent_selector`      | `visible`, `hidden` or `null` | `null` removes the workspace's own value                                                          |

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 [#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:

   ```bash
   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`.

| Response                                                      | Cause                                                                      |
| ------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `422 The default space cannot be deleted`                     | The workspace is the user's default workspace                              |
| `403 Only the space creator can delete this space`            | The caller did not create it; platform admins use the platform-admin route |
| `502 Failed to reach the workflow engine. Space not deleted.` | A dependent service was unreachable; nothing was deleted, so retry later   |