AimableDocs
DocsAPI ReferenceRelease Notes

Integration patterns

DeveloperUpdated 9 July 2026

Organizing spaces

A space is your isolation boundary: its own model policy, knowledge, tools, governance settings, and usage accounting. How you map spaces is your decision — a space might represent a customer, an environment (production vs. staging), an application, or a team. Whatever you choose, mapping to spaces gives you:

  • Data and knowledge that never mix across spaces.
  • Different models, prompts, or guards per space.
  • Usage and cost attributable per space (see Usage & metering).

Your application keeps a mapping from your own identifier to the Aimable space_id, and sets X-Aimable-Space-Id on each request.

Credential strategy

An API key authenticates a service principal within your tenant, and a request's space is chosen per call. That gives you two workable shapes:

  • One key per space (recommended). Create a service principal and key per space, with the principal a member of only that space. Blast radius is a single space if a key leaks, and revoking a key affects only that space.

  • One shared key across spaces. A single principal that is a member of many spaces can serve all of them, selecting the space per request. Simpler to manage, but a leaked key exposes every space it can reach. Use only when the spaces are not mutually untrusted.

Whichever you choose, keys are rotatable and revocable — rotate on a schedule and revoke on exposure.

Choosing the endpoint

  • POST /v1/chat/completions — OpenAI-compatible. The lowest-friction path: point an existing OpenAI client at Aimable's base URL, add X-API-Key and X-Aimable-Space-Id, and you are done. Best for straightforward chat/completion workloads.

  • POST /v1/spaces/{space_id}/responses — the governed path. Use it when you want Aimable to apply PII pseudonymization, input/output guards, knowledge search, tools, and per-call cost caps to each request, and when you want structured output and response chaining.

A common approach is to start on /v1/chat/completions to validate connectivity and latency, then move governed workloads to /responses.

Model routing

Each space's model policy decides which models are reachable:

  • fixed — every request uses the space's default model. Use this to pin a space to one model regardless of what the caller asks for.
  • user_select — the caller picks from a curated allow-list; the default applies when none is named.
  • auto — reserved for policy-driven routing across the allowed set; today it resolves to the space's default model.

Because the model is resolved server-side from the space policy, you can change a space's model — or restrict an expensive one — without any change in the integration code. Requests for a model the space does not allow are rejected with 403.

Knowledge and tools

A space can have collections (for retrieval), tools, and skills attached. Once configured, the same inference request can use them — for example by passing collection ids for retrieval-augmented generation, or by enabling the space's tools on the governed endpoint. See Collections and Tools.

Next steps