API Overview
OptimaGPT exposes an OpenAI-compatible HTTP API. Any application or library that supports the OpenAI API can be pointed at OptimaGPT instead, with no code changes beyond the base URL and authentication credentials.
Base URL
All API requests are made to your Gateway's address. The base URL follows this pattern:
https://<your-gateway-address>
For example: https://optima.yourcompany.com
Available endpoints
| Endpoint | Method | Description |
|---|---|---|
/v1/chat/completions |
POST | Generate a chat response from a language model |
/v1/embeddings |
POST | Generate vector embeddings from an embedding model |
/v1/responses |
POST | Stateful responses with optional conversation chaining |
/optima/v1/models |
GET | List available models and their metadata |
/optima/v1/capabilities |
GET | Check what the gateway can currently do |
/optima/v1/conversations |
GET, PUT, DELETE | Manage saved chat conversations |
/api/auth/login |
POST | Obtain an access token |
/api/auth/refresh |
POST | Refresh an expired access token |
/api/auth/logout |
POST | Invalidate a session |
Authentication
All API endpoints (except the auth endpoints themselves) require authentication. OptimaGPT supports two authentication methods:
- JWT bearer tokens — obtained by logging in via
/api/auth/login. Short-lived; refreshed automatically. - API keys — long-lived keys created by an administrator. Suitable for integrations and automation.
See Authentication for full details.
OpenAI compatibility
The /v1/chat/completions and /v1/embeddings endpoints follow the OpenAI API specification. If you are using the official OpenAI Python or Node.js SDK, or any framework with OpenAI support, configure it as follows:
Python (openai library):
from openai import OpenAI
client = OpenAI(
base_url="https://optima.yourcompany.com/v1",
api_key="your-optima-api-key"
)
Node.js (openai library):
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://optima.yourcompany.com/v1',
apiKey: 'your-optima-api-key',
});
The model field in your request should reference a model ID from OptimaGPT's model list. Use the /optima/v1/models endpoint to discover available model IDs.
Content type
All request and response bodies use JSON (Content-Type: application/json). Streaming responses use Server-Sent Events (text/event-stream).
Error responses
Errors are indicated by HTTP status codes. The response body is either a plain-text message or, for routing and service errors, a JSON object:
{ "error": "No nodes available to handle the request" }
Common status codes:
| Code | Meaning |
|---|---|
| 400 | Bad request — malformed JSON or missing required fields |
| 401 | Unauthorized — missing or invalid credentials |
| 403 | Forbidden — authenticated but lacking permission |
| 404 | Not found — model or resource does not exist |
| 500 | Internal server error |
| 503 | Service unavailable — the gateway has no nodes available or is not yet ready |