Licensed to be used in conjunction with basebox, only.
// integration
Quickstart
Applies to
Product: Cloud · Server · Audience: Developer / Integrator
Your first successful chat completion in a few minutes: get an API key, determine base URL and realm for your environment, send a request with curl, then do the same with the OpenAI SDK. Everything else – streaming, errors, tool calling – is on the linked pages.
1. Get an API key
API keys are issued by an administrator of your organisation: Administration → API keys → "Create API key". The key is shown only once. It applies to your organisation and all models enabled for it – see API permissions.
On basebox Server the REST API must also be enabled (AISRV_ENABLE_REST_API=true, a Platform Operator task); otherwise the section is missing from the administration.
2. Determine base URL and realm
| basebox Cloud | basebox Server | |
|---|---|---|
| Base URL | https://aims.basebox.ai |
The address of your installation, e.g. https://basebox.company.internal |
X-Realm |
Your subdomain, e.g. myorg |
Usually primary – check under user menu → "About", line Realm |
You need both values in every request.
3. Check the connection
export BASEBOX_URL="https://your-org.basebox.ai"
export BASEBOX_REALM="your-org"
export BASEBOX_API_TOKEN="<your-token>"
curl -s "$BASEBOX_URL/v1/models" \
-H "Authorization: Bearer $BASEBOX_API_TOKEN" \
-H "X-Realm: $BASEBOX_REALM"
The response lists the models your organisation may use. Use one of these identifiers as model in the next step. A 401 means "Bearer " is missing or the key is wrong; a 403 means the licence does not cover the API or the realm does not match.
4. First chat completion
curl -s -X POST "$BASEBOX_URL/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $BASEBOX_API_TOKEN" \
-H "X-Realm: $BASEBOX_REALM" \
-d '{
"model": "<model-id-from-step-3>",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Say hello in one sentence."}
],
"stream": false
}'
You receive an OpenAI-compatible chat.completion object with choices[0].message.content and a usage block.
5. The same with the OpenAI SDK
Every OpenAI client library works if you point base_url at /v1 of your instance and pass the X-Realm header as a default header:
from openai import OpenAI
import os
client = OpenAI(
base_url=f"{os.environ['BASEBOX_URL']}/v1",
api_key=os.environ["BASEBOX_API_TOKEN"],
default_headers={"X-Realm": os.environ["BASEBOX_REALM"]},
)
models = client.models.list()
model_id = models.data[0].id
response = client.chat.completions.create(
model=model_id,
messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(response.choices[0].message.content)
Node.js, Go, .NET and other SDKs behave the same: base URL, API key, default header.
6. Keep exploring interactively
Swagger UI is available at $BASEBOX_URL/v1/api/docs: enter the token via Authorize, execute endpoints, inspect schemas and copy the generated curl command. Guide: Testing with Swagger UI.
The REST variant
Besides the OpenAI-compatible API there is the REST endpoint POST /rest/v1/chat/completions with the same header scheme. The model there is ai.basebox.assistant. Details: REST API · Authentication.
Where to go next
- Receive answers progressively: Streaming
- Handle errors properly (401, 403, 404, timeouts, context too large): Error handling
- Control thinking modes via the API: Reasoning effort
- Connect an editor or coding agent: IDE integration · OpenClaw integration
- Full reference with examples and common mistakes: User guide
Treat the key like a password
Never check it into Git; always load it from environment variables or a secret store. A compromised key is deleted and reissued by the administrator.