Getting Started

Introduction

This guide takes you from credentials to a working response. By the end you will have sent a request through Aimable to a model and received a completion — using the OpenAI-compatible endpoint, so most existing clients work with only a base-URL change.

Prerequisites

You need three things, all included with your evaluation access:

• A base URL — your per-tenant gateway: https://<your-tenant>.aimable.ai/api (the <your-tenant> subdomain is specific to your account). Every endpoint path below starts with /v1, so a full URL looks like https://<your-tenant>.aimable.ai/api/v1/chat/completions. The previous /api-proxy prefix remains supported for existing integrations.
• An API key — a service credential in the form ak.<key_id>.<secret>. Treat it like a password; it is shown only once when created.
• A space ID — the workspace your request runs in. Every request runs in the context of a space. If you do not have one yet, see Provisioning.

Store the key and base URL as environment variables — never commit them:

export AIMABLE_BASE_URL="https://<your-tenant>.aimable.ai/api"
export AIMABLE_API_KEY="ak.your_key_id.your_secret"
export AIMABLE_SPACE_ID="your-space-uuid"

1. Make your first request

Aimable exposes an OpenAI-compatible chat completions endpoint. Authenticate with the X-API-Key header and select the space with X-Aimable-Space-Id:

curl -X POST "$AIMABLE_BASE_URL/v1/chat/completions" \
  -H "X-API-Key: $AIMABLE_API_KEY" \
  -H "X-Aimable-Space-Id: $AIMABLE_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello, Aimable!" }
    ]
  }'

You can name a model in the body, but you do not have to — if you omit it, the space's model policy chooses the default. To see which models a space allows, call GET /v1/spaces/{space_id}/models; GET /v1/models lists the full catalogue.

2. Read the response

The response follows the OpenAI chat-completions shape:

{
  "id": "chatcmpl-...",
  "model": "...",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help you today?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 9, "completion_tokens": 11, "total_tokens": 20 }
}

Two response headers worth noting:

• X-Request-Id — a unique id for the call; quote it when contacting support.
• X-Routing-Details — JSON describing how the model was resolved and which governance was applied.

3. Stream the response

Set "stream": true to receive Server-Sent Events. Each event is a data: line, and the stream ends with data: [DONE]:

curl -N -X POST "$AIMABLE_BASE_URL/v1/chat/completions" \
  -H "X-API-Key: $AIMABLE_API_KEY" \
  -H "X-Aimable-Space-Id: $AIMABLE_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": true,
    "messages": [
      { "role": "user", "content": "Write a haiku about governance." }
    ]
  }'

Each chunk carries incremental content at choices[0].delta.content.

Next steps

• Integration — authentication options, choosing models, streaming, and error handling in production.
• Provisioning — create a space and set its model policy via the API.
• Concepts — the data model behind tenants, spaces, and model policy.