Integration

Overview

This guide covers what you need to build a production integration on top of Aimable: how to authenticate, how requests are scoped to a space, which endpoint to use, how to select models, and how to handle streaming and errors.

Authentication

Aimable accepts two credential types. Pick one per request — do not send both.

• API key (machine-to-machine). Pass it in the X-API-Key header. This is the right choice for backend services.

  bashCopy

  X-API-Key: ak.<key_id>.<secret>

  An API key is a service credential bound to a non-human principal within your tenant. The plaintext secret is shown only once, at creation, and stored hashed. Keys can be rotated and revoked — see Provisioning.

• Bearer token (user sessions). A short-lived JWT in the Authorization header, used when a human is signed in.

  bashCopy

  Authorization: Bearer <jwt>

For backend services integrating Aimable as a gateway, use the API key.

Spaces: scoping every request

Every inference request runs in the context of a space. The space determines which models are allowed, which governance applies (PII handling, guards), and which knowledge and tools are available. How you map spaces is your choice — by customer, environment, application, or team.

How you name the space depends on the endpoint:

• On POST /v1/chat/completions, pass the space in the X-Aimable-Space-Id header.
• On POST /v1/spaces/{space_id}/responses, the space is part of the path.

Your API key's principal must have access to the space it is used with.

Choosing an endpoint

Start with /v1/chat/completions. Move to /responses when you need Aimable's governance features applied to each call.

Selecting a model

Name the model in the model field of the request body, or override it with the X-Model header. If you omit it, the space's model policy supplies the default.

{
  "model": "gpt-4o",
  "messages": [{ "role": "user", "content": "..." }]
}

Which models are usable is governed per space: a policy mode (fixed, user_select, or auto), an allow-list, and a default. If you request a model the space does not allow, the call is rejected with 403. List available models with GET /v1/models, and see Space model policy for how the allow-list is configured.

Streaming

Set "stream": true to receive Server-Sent Events (Content-Type: text/event-stream). Each event is a data: {json} line; long operations may emit : ping heartbeat lines, which you should ignore. The stream terminates with:

data: [DONE]

Incremental text arrives at choices[0].delta.content. For reasoning models, reasoning text arrives at choices[0].delta.reasoning_content.

Handling responses and errors

Successful calls return 200. Errors use a consistent envelope:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": { }
  }
}

Common statuses:

• 400 Bad Request — invalid parameters; read error.message.
• 401 Unauthorized — missing or invalid credential.
• 403 Forbidden — the principal lacks access to the space, or the requested model is not allowed by the space's policy.
• 429 Too Many Requests — rate limit exceeded; retry after the Retry-After header.
• 500 Internal Server Error — unexpected error; retry transient failures and quote X-Request-Id to support.

The /responses endpoint applies a per-principal rate limit (30 requests/minute) and returns 429 with Retry-After when exceeded. Build retry-with-backoff for 429 and 500.

Observability headers

Every response carries X-Request-Id (quote it in support requests) and X-Routing-Details (JSON describing model resolution and applied governance). You can pass X-Trace-Id and X-Parent-Span-Id to correlate calls with your own tracing. See Observability for per-space usage and cost metrics.

Next steps

• Provisioning — create spaces and API keys via the API.
• Integration patterns — organizing spaces, and routing strategies.
• Usage & metering — read per-space token, cost, and latency metrics.