Using the API

Optiak exposes OpenAI-compatible endpoints for application traffic. You can call the HTTP API directly or point the OpenAI SDK at the Optiak base URL.

The public API base URL is:

https://api.optiak.dev/v1

Authenticate every request with an application API key:

Authorization: Bearer <application-api-key>

Use an application API key from Applications -> your application -> Credentials. Provider keys are only used inside Optiak to call model providers.

Environment

Set the public base URL and your application API key:

export OPTIAK_BASE_URL="https://api.optiak.dev/v1"
export OPTIAK_API_KEY="your_application_api_key"

Endpoints

Supported public endpoints, relative to https://api.optiak.dev/v1:

• GET /models
• POST /chat/completions
• POST /responses

Use Models to discover the public model IDs available to an application key. Use Chat Completions when you already have code built around OpenAI-style chat messages. Use Responses for integrations that prefer a single input field, structured outputs, and semantic streaming events.

Models

Use GET /models to list the models available to the application API key.

import os
import requests

response = requests.get(
    os.environ["OPTIAK_BASE_URL"] + "/models",
    headers={
        "Authorization": f"Bearer {os.environ['OPTIAK_API_KEY']}",
    },
)
response.raise_for_status()

models = response.json()
for model in models["data"]:
    print(model["id"])

The response uses an OpenAI-style list wrapper:

{
  "data": [
    {
      "id": "openai/gpt-5-nano",
      "model_name": "gpt-5-nano",
      "description": "Fast model for lightweight tasks.",
      "model_type": "inference",
      "context_window": 128000,
      "input_modalities": ["text"],
      "output_modalities": ["text"],
      "features": ["chat_completion_api", "responses_api"],
      "zero_data_retention": false,
      "no_data_training": true,
      "data_residency": "US",
      "cost_model": {
        "input_tokens": 0.05,
        "output_tokens": 0.4,
        "currency": "USD",
        "pricing_version": "v1"
      },
      "smart_routing": true
    }
  ]
}

The id field is the public model ID to use in requests.

Model Selection

The model field controls model selection.

Use a specific public model ID:

{
  "model": "openai/gpt-5-nano"
}

Use Smart Router:

{
  "model": "smart"
}

smart only works when Smart Router is enabled for the application and at least one smart-routing-eligible model is enabled for that application.

All examples below use smart. To route directly to a provider model, replace the model value in the same request shape with a public model ID returned by /models, such as openai/gpt-5-nano.

Chat Completions

Use POST /chat/completions for message-based conversations.

import os
import requests

response = requests.post(
    os.environ["OPTIAK_BASE_URL"] + "/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPTIAK_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "smart",
        "messages": [
            {"role": "user", "content": "Write a short product FAQ."}
        ],
        "temperature": 0.2,
    },
)
response.raise_for_status()

completion = response.json()
print(completion["choices"][0]["message"]["content"])

Responses

Use POST /responses for the newer OpenAI-compatible Responses shape.

import os
import requests

response = requests.post(
    os.environ["OPTIAK_BASE_URL"] + "/responses",
    headers={
        "Authorization": f"Bearer {os.environ['OPTIAK_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "smart",
        "input": "Write three onboarding tips for a new user.",
    },
)
response.raise_for_status()

result = response.json()
print(result.get("output_text") or result["output"][0]["content"][0]["text"])

Streaming

Both inference endpoints support streaming with stream: true.

Chat Completions Streaming

import os
import requests

with requests.post(
    os.environ["OPTIAK_BASE_URL"] + "/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPTIAK_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "smart",
        "messages": [
            {"role": "user", "content": "Write a concise launch checklist."}
        ],
        "stream": True,
    },
    stream=True,
) as response:
    response.raise_for_status()
    for line in response.iter_lines(decode_unicode=True):
        if line:
            print(line)

Responses Streaming

import os
import requests

with requests.post(
    os.environ["OPTIAK_BASE_URL"] + "/responses",
    headers={
        "Authorization": f"Bearer {os.environ['OPTIAK_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "smart",
        "input": "Write a concise launch checklist.",
        "stream": True,
    },
    stream=True,
) as response:
    response.raise_for_status()
    for line in response.iter_lines(decode_unicode=True):
        if line:
            print(line)

Request-Level Enrichment

If an application has web search or vector search set to Per request, the caller can opt in per request.

For Chat Completions:

{
  "model": "smart",
  "messages": [
    { "role": "user", "content": "What changed in our uploaded policy?" }
  ],
  "vector_search_enabled": true,
  "web_search_enabled": true
}

For Responses:

{
  "model": "smart",
  "input": "Find current context and answer briefly.",
  "vector_search_enabled": true,
  "web_search_enabled": true
}

Organization and application settings still apply. Request-level flags can opt into available modules, but they cannot force on a module that is disabled or blocked by policy.

SDK Compatibility

Optiak does not require a proprietary SDK. For most applications, use direct HTTP calls or the official OpenAI SDK with:

• apiKey or api_key set to the application API key.
• baseURL or base_url set to https://api.optiak.dev/v1.
• model set to smart or to a model available in the application.

Common Errors

• 400 - Missing bearer token, malformed payload, unknown provider or model, or smart used when Smart Router is not enabled.
• 401 - Invalid key, revoked key, expired key, or inactive application.
• 403 - A guardrail blocked the request in forbidden mode.
• 422 - The request is valid, but no eligible model can currently process it.
• 500 - Unexpected service error.

Error responses use this shape:

{
  "error": {
    "type": "bad_request",
    "message": "Missing or invalid Authorization header."
  }
}