Skip to content
Olympusx AIOlympusx AIOlympusx AI documentation

API overview

Olympusx AI exposes models through an OpenAI-compatible HTTP API on the gateway. Applications, SDKs and tools written for OpenAI work by changing the base URL and the key. This page covers what every call has in common. It is for developers integrating an application, and for the platform team publishing the gateway.

Base URL

Section titled “Base URL”
https://<your-gateway-host>/v1

Your platform team publishes the gateway on its own host name, separate from the console’s. The codebase tools for editors are served beside the API, at https://<your-gateway-host>/mcp.

Authentication

Section titled “Authentication”

Every request carries an Olympusx AI API key, in either header:

Authorization: Bearer olp_...
x-api-key: olp_...
  • A key is created by a tenant admin in Govern › Keys and budgets, or by a developer for their own editor on the Code Assistant page. See Keys, budgets and metering.
  • The key decides the tenant and project the call is billed to. Nothing in the request can change that.
  • A sign-in token from the console is refused with 401 jwt_unsupported. The gateway takes keys only.

Endpoints

Section titled “Endpoints”
Method and path What it does Page
POST /v1/chat/completions Chat, with streaming and tool calls Chat completions
POST /v1/completions Text completion Chat completions
POST /v1/embeddings Vectors for text Embeddings and reranking
POST /rerank Scores documents against a query Embeddings and reranking
GET /v1/models The models this key’s tenant can call now Models
POST /mcp The codebase tools, for developer keys Code tools

Every request except GET /v1/models and /mcp must name its model in a JSON body field model, exactly as the catalog names it. A request without one is refused with 400 model_required.

OpenAI compatibility

Section titled “OpenAI compatibility”

Requests and responses follow the OpenAI API for the endpoints above. Request parameters such as temperature, max_tokens, tools, response_format or stream are passed to the model’s runtime. Olympusx AI adds two rules of its own:

  • Streaming always ends with usage. On a request with stream: true, Olympusx AI sets stream_options.include_usage, so the last chunk of the stream carries the token counts. See Streaming.
  • Every refusal has the OpenAI error shape, with an Olympusx AI reason in code. See Errors.

Python, with the OpenAI SDK

Section titled “Python, with the OpenAI SDK”
import os
from openai import OpenAI


client = OpenAI(
    base_url="https://<your-gateway-host>/v1",
    api_key=os.environ["OLYMPUS_API_KEY"],
)


reply = client.chat.completions.create(
    model="<model-name>",
    messages=[{"role": "user", "content": "Summarise our refund policy in two sentences."}],
)
print(reply.choices[0].message.content)

curl

Section titled “curl”
curl -s https://<your-gateway-host>/v1/chat/completions \
  -H "Authorization: Bearer $OLYMPUS_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"model":"<model-name>","messages":[{"role":"user","content":"Hello"}]}'

Request identifiers

Section titled “Request identifiers”

Each completion response carries the id the model’s runtime assigned (chatcmpl-...). The gateway records every request with its tenant, project, key, model, token counts and time, which is how it appears in Govern › Usage. To match a call to its record, log the response id, the key ID and the time on your side.

Errors, limits and retries

Section titled “Errors, limits and retries”
  • Refusals are listed in Errors. 401 means fix the key, 403 means ask for access, 429 means a budget or rate limit, 503 means retry.
  • Time limits, sizes and rate limits are in Limits.
  • A 503 from the gateway is a platform condition and is safe to retry with backoff. A 429 with insufficient_quota will not succeed until the budget period rolls over.

The management API

Section titled “The management API”

Everything the console does, it does through the management API, and you can call it too: to automate tenant administration, issue keys from a pipeline, or read usage into your own reports.
Base URL https://<your-console-host>/api/v1
Authentication Authorization: Bearer <token>: an access token your identity provider issued to a person signed in to the console. API keys are not accepted.
Permissions The person’s role, exactly as in the console. See Roles.
Contract Described in these pages for the calls customers use.

Some settings are available only here:

A key limited to named models. The console’s key wizard issues keys that may call every model granted to the tenant. To limit a key, create it with modelAllowlist. An Admin of the tenant can do this:

curl -s -X POST https://<your-console-host>/api/v1/projects/<project-id>/keys \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"claims-service","modelAllowlist":["<model-name>"],"expiresInDays":90}'

The response holds the key’s id, kid, modelAllowlist, expiresAt and secret. The secret is returned once. expiresInDays is 1 to 3,650; leave it out for a key that never expires. A call for a model outside the allow-list is refused with 403 model_not_allowed.

Guardrail thresholds and personal-data types. GET and PUT /api/v1/tenants/<tenant-id>/guardrail-policy read and write the whole policy, including piiEntities (the personal-data types to detect; empty means the scanner’s general set) and thresholds (scores for toxicity, prompt_injection and ban_topics). An Admin or Builder can write it. See Guardrails.

Retention windows. PUT /api/v1/platform/retention, platform administrators only. See Data retention.

Section titled “Related”