Get started

Create an API key and make your first call to the Alomana API.

Prerequisites

An Alomana account and a workspace where your role is Editor or Admin; a Member cannot create API keys.
A plan that includes API keys. Without one, creating a key returns 402 with code FEATURE_NOT_AVAILABLE.
The base URL of each service you call, from Base URLs.

Base URLs

Service	Base URL
Alomana API: workspaces, agents, connectors	`https://platform.alomana.com`
Files	`https://alo-files-service-103105631559.europe-west8.run.app`
Vox	`https://agent-vox-service-103105631559.europe-west8.run.app`

An enterprise deployment has its own URLs; ask your administrator for them.

Make your first call

In the web app, open Settings → Workspace → API Keys and create a key; on an enterprise deployment, open the same page on your own host. Copy it now: the full key is shown only once.

Store the key, the API base URL and the workspace slug in environment variables:

export CENTRAL_HUB_URL="https://platform.alomana.com"
export ALO_API_KEY="sk-…"
export WORKSPACE_SLUG="acme-analytics"

Read the workspace the key belongs to:

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

The response is the workspace and your role in it:

{
  "id": 280,
  "slug": "acme-analytics",
  "name": "Acme Analytics",
  "status": "active",
  "is_default": false,
  "created_by_id": 244,
  "updated_by_id": 244,
  "created_at": "2026-10-13T16:00:37.844766Z",
  "updated_at": "2026-10-13T16:00:37.844767Z",
  "role_slug": "admin",
  "role_name": "Admin",
  "organization_id": null,
  "is_creator": false,
  "created_by_email": null,
  "member_count": 1,
  "is_shared": false
}

List the agents you can run in this workspace:

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

A new workspace returns three agents: Alo, App Builder and Agent Builder.

Troubleshooting

Response	Cause	Fix
`401` `{"detail": "Valid API key or Bearer token required"}`	The key is wrong, deleted, past its expiration date, or its owner is disabled	Check the key in Settings → Workspace → API Keys; regenerate it if needed
`403` `{"detail": "API key is restricted to space 'acme-analytics'"}`	`X-Space-Slug` is missing or names another workspace	Send the slug of the workspace the key was created in
`402` `FEATURE_NOT_AVAILABLE` when creating a key	Your plan does not include API keys	Upgrade the plan

Use from a coding agent

Install the Alomana skill so Claude Code, Cursor, Codex and other coding agents read these docs and make the calls for you:

npx skills add aidataspark/alomana-skills

In Claude Code you can also install it as a plugin: /plugin marketplace add aidataspark/alomana-skills, then /plugin install alomana@alomana-skills.