Alloovium

Get Started

Quickstart

From zero to your first successful API call in under five minutes. This walkthrough uses an API key; for OAuth flows see Authentication.

1. Create an API key

Sign in and open the Developer Console, then click Create API key to open key management. Give the key a name and pick an environment:

  • prefix — keys prefixed code. Use these for production traffic.
  • prefix — keys prefixed code. Use these in CI and local development. They can talk to either environment.

One chance to copy

The raw key is only shown once at creation time. Store it in a secret manager. If you lose it, revoke it and create a new one.

Keys look like this: example. They carry the user, tenant, environment, tier, and scope set.

$100 in free credits included

New developer accounts start with 100,000 free API credits — worth $100 at $0.001 per credit — so you can validate your integration before committing to paid traffic. No credit card required. Monitor usage from the Developer Console.

2. Authenticate every request

Send the key as an HTTP header header. Do not put the key in a query string, cookie, or request body.

http
GET /api/v2/me HTTP/1.1
Host: api.alloovium.com
Authorization: Bearer ak_live_AB7K2LJ...
Accept: application/json

3. Call your first endpoint

The path endpoint is the recommended health check. It costs 1 rate-limit token, requires no scope, and returns the full principal behind your credential.

bash
curl -sS https://api.alloovium.com/api/v2/me \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY"

Response

json
{
  "user_id": "1f02d9ef-2b33-4d1d-9c4a-82f06a91e3d1",
  "tenant_id": "c7a1e9c2-9c1e-4e4e-bf97-a4b5e76cf9c8",
  "auth_method": "api_key",
  "email": "alex@example.com",
  "api_key_id": "5e2f09bb-9c1e-4e4e-bf97-a4b5e76cf9c8",
  "api_key_name": "Production Backend",
  "api_key_prefix": "ak_live_AB7K",
  "environment": "live",
  "rate_limit_tier": "standard",
  "scopes": [
    "vault:read",
    "vault:write",
    "chat:read",
    "chat:write"
  ]
}

4. List your projects

Now call a scoped endpoint. This one needs scope, costs 1 token, and is cursor paginated.

bash
curl -sS "https://api.alloovium.com/api/v2/vault/projects?limit=10" \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY"
json
{
  "data": [
    {
      "id": "8f2e3c1a-...",
      "name": "Downtown Tower",
      "description": "Mixed-use high-rise.",
      "project_type": "commercial",
      "status": "active",
      "created_at": "2026-04-02T10:12:34+00:00"
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0wMlQxMDoxMjozNCswMDowMCIsImlkIjoiOGYyZTNjMWEifQ",
  "has_more": true
}

Pass cursor back as param to fetch the next page. See Pagination for the full envelope.

5. Handle errors

Every 4xx / 5xx response follows the RFC 7807 problem-detail envelope. Branch on the field field — never on human strings or status codes alone.

json
{
  "type": "https://api.alloovium.com/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "API key is missing required scope: vault:write",
  "code": "insufficient_scope",
  "missing_scopes": ["vault:write"]
}

See the full list of codes in Errors.

6. Retry safely

For mutating requests, attach an header header. The same key replayed within 24 hours returns the original response — no duplicate writes.

bash
curl -sS https://api.alloovium.com/api/v2/vault/projects \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY" \
  -H "Idempotency-Key: create-tower-2026-04-08" \
  -H "Content-Type: application/json" \
  -d '{"name": "Downtown Tower", "project_type": "commercial"}'

Next steps