Workspace API

The ordinary Alomana workspace API can be called by Claude Code, another external agent, a CI job, or any HTTP client. No built-in Alo agent integration is required.

There is no separate automation endpoint. Programmatic clients use the same workspace URLs as the web application:

Authentication and key scopes

Interactive clients may send a bearer token:

Authorization: Bearer <oidc-token>
X-Space-Slug: acme-manufacturing

External agents normally send an API key:

X-API-Key: sk-...
X-Space-Slug: acme-manufacturing

The two API-key types have different boundaries:

A workspace key receives 403 Forbidden if X-Space-Slug names another workspace. A platform-wide key has no issuing-workspace lock, but it still acts as its owner and cannot access a workspace the owner cannot access.

API-key management remains bearer/UI-only. An API key cannot create, regenerate, or delete another key. Account-wide workspace listing, first-workspace creation, members, invites, roles, and permissions are also bearer-only.

Store credentials in environment variables or a protected temporary file. Never commit or print a raw key; it is shown only when created or regenerated.

Discover domain agents by tag

Manufacturing, Finance, and Pharma agents are ordinary global Alo agents. Discover them through tags instead of a workspace industry type:

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: $SOURCE_SPACE_SLUG"

Use tag_in=finance or tag_in=pharma for the other domains. The response supplies the agent IDs needed by workspace settings and landing suggestions.

Create a Manufacturing workspace in one call

Only a bearer caller or platform-wide key can create an additional workspace. The server generates the slug; do not send one.

curl -X POST "$CENTRAL_HUB_URL/api/v1/spaces/" \
  -H "X-API-Key: $ALO_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA MANUFACTURING ADMIN",
    "initial_settings": {
      "default_agent_id": 42,
      "landing_suggestions": [
        {
          "agent_id": 42,
          "active": true,
          "label": "Review OEE",
          "prompt": "Analyze manufacturing OEE and recommend improvements.",
          "icon": "factory",
          "model_config_id": null,
          "categories": []
        },
        {
          "agent_id": 43,
          "active": true,
          "label": "Predict downtime",
          "prompt": "Review maintenance signals and identify likely equipment failures.",
          "icon": "wrench",
          "model_config_id": null,
          "categories": []
        }
      ]
    }
  }'

The response is the normal workspace object, including its server-generated slug.

Creation is atomic. Alomana creates the workspace, default roles, creator membership, required agent installations, settings, and suggestions in one transaction. Agent and model references follow the same validation as later settings edits. An invalid reference returns 422 Unprocessable Entity and rolls back the complete workspace. Global agents referenced by the default agent, suggestions, or suggestion examples are installed automatically.

Name-only creation remains valid:

{ "name": "Manufacturing Operations" }

Workspace agent membership

An installation is the complete workspace membership state for a global agent:

• Alo, App Builder, and Agent Builder are installed automatically and cannot be removed.
• Every other Alo or Store agent remains catalog-only until explicitly installed.
• An installed agent appears in workspace lists and may run; an uninstalled agent does neither.
• Workspace-owned agents belong directly to their workspace and do not need an installation row.

Use show_platform=true to browse the complete global catalog. Each result has an installed flag for the selected X-Space-Slug.

# Install an optional agent
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"

# Remove it again
curl -X DELETE "$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"

Both platform-wide and workspace-scoped keys may manage installations within their normal workspace boundary. Removing a required agent, the current default, or an agent used by an active workspace suggestion returns 422; update those references first. Later settings edits may reference only workspace-owned or already installed agents. One-call creation is the exception because it installs its referenced globals inside the same transaction.

Read, rename, and edit settings

Every current route selects its workspace with X-Space-Slug.

# Read the workspace
curl "$CENTRAL_HUB_URL/api/v1/spaces/current/" \
  -H "X-API-Key: $ALO_API_KEY" \
  -H "X-Space-Slug: $WORKSPACE_SLUG"

# 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":"QA MANUFACTURING ADMIN — EDITED"}'

# Read effective settings
curl "$CENTRAL_HUB_URL/api/v1/spaces/current/settings/" \
  -H "X-API-Key: $ALO_API_KEY" \
  -H "X-Space-Slug: $WORKSPACE_SLUG"

# Replace the workspace suggestion override
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": [
      {
        "agent_id": 42,
        "active": true,
        "label": "Improve OEE",
        "prompt": "Find the largest OEE loss and propose a prioritized improvement plan.",
        "icon": "factory",
        "model_config_id": null,
        "categories": []
      }
    ]
  }'

An empty landing_suggestions list removes the workspace override and restores platform-default inheritance.

Scoped-key verification

After creating a normal workspace key in the UI, verify both sides of its boundary:

# Its own workspace succeeds
curl "$CENTRAL_HUB_URL/api/v1/spaces/current/" \
  -H "X-API-Key: $ALO_WORKSPACE_API_KEY" \
  -H "X-Space-Slug: $WORKSPACE_SLUG"

# Another workspace is rejected with 403
curl "$CENTRAL_HUB_URL/api/v1/spaces/current/" \
  -H "X-API-Key: $ALO_WORKSPACE_API_KEY" \
  -H "X-Space-Slug: $OTHER_WORKSPACE_SLUG"

Delete only after confirmation

Workspace deletion is creator-only, and the default workspace cannot be deleted. The successful response is 204 No Content.

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

For review or QA workspaces, leave them available until a human explicitly confirms deletion. After deletion, a GET of the same selected workspace returns 404 Not Found.