Optiak Docs
Reference

Using the API

How to call Optiak from your application.

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 Projects -> your application -> API keys. Provider keys are only used inside Optiak to call model providers.

For an interactive, browsable view of every endpoint and schema, see the API Reference.

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)

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.
  • 402 - The organization exhausted its monthly API request limit (monthly_api_request_quota_exceeded).
  • 403 - A guardrail blocked the request in forbidden mode, or a Block requests budget is exhausted (budget_limit_exceeded).
  • 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."
  }
}
Copyright © 2026