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

# Get started

Get started [#get-started]

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

Prerequisites [#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).

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 [#make-your-first-call]

1. In the web app, open [**Settings → Workspace → API Keys**](https://platform.alomana.com/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.

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

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

3. Read the workspace the key belongs to:

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

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

4. List the agents you can run in this workspace:

   ```bash
   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 [#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**](https://platform.alomana.com/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 [#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:

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

Next steps [#next-steps]

* [Run an agent and stream its events](./configurable-agents/run-and-stream)
* [Authentication and API keys](./api-basics/authentication)
* [Errors](./api-basics/errors)