API Overview
OnVeris exposes an OpenAI-compatible HTTP API. Applications and libraries that support the OpenAI API can be pointed at OnVeris instead, by changing the base URL and the API Key. You can use the API to add OnVeris's models and Assistants to your own applications, scripts and integrations, while your data stays on your own servers.
Base URL
All API requests are made to your Gateway's address:
https://<your-gateway-address>
For example: https://onveris.yourcompany.com
Available Endpoints
The following endpoints are covered in this section. Each needs the scope shown.
| Endpoint | Method | Description | Scope |
|---|---|---|---|
/v1/chat/completions |
POST | Generate a chat response from a model or Assistant | chat.completions |
/v1/responses |
POST | Stateful responses, with conversation history kept by the Gateway | responses |
/v1/embeddings |
POST | Generate vector embeddings | embeddings |
/v1/models |
GET | List models and Assistants, in OpenAI's format | models.read |
/onveris/v1/models |
GET | List models and Assistants, with OnVeris's extra detail | models.read |
/onveris/v1/capabilities |
GET | Check what the Gateway can currently do | — |
/onveris/v1/conversations |
GET, PUT, DELETE | Legacy: manage saved conversations | — |
/api/auth/login |
POST | Obtain an access token | — |
/api/auth/refresh |
POST | Refresh an expired access token | — |
/api/auth/logout |
POST | End a session | — |
/api/auth/change-password |
POST | Change the signed-in user's password | — |
OnVeris also has APIs for Knowledge Bases (/onveris/v1/knowledge), Assistants (/onveris/v1/assistants), documents and Node status, used by its own apps. These are not covered here.
Note
Before OnVeris was renamed, these endpoints were under /optima/v1. They still answer there, so an existing integration keeps working without any change. Use /onveris/v1 in anything new. A Gateway that has not been updated since the rename answers only /optima/v1.
Authentication
Every endpoint except the sign-in endpoints needs credentials. You can use either:
- API Keys — created by an administrator, or by a user for themselves. Best for integrations and automation.
- Access tokens — obtained by signing in through
/api/auth/login. Short-lived.
Each endpoint needs a scope, shown in the table above. A key can only call the endpoints whose scopes it holds. See Authentication.
OpenAI Compatibility
/v1/chat/completions, /v1/responses, /v1/embeddings and /v1/models follow the OpenAI API. You can use the official OpenAI Python or Node.js library, or any framework with OpenAI support. Configure it like this:
Python (openai library):
from openai import OpenAI
client = OpenAI(
base_url="https://onveris.yourcompany.com/v1",
api_key="your-onveris-api-key"
)
Node.js (openai library):
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://onveris.yourcompany.com/v1',
apiKey: 'your-onveris-api-key',
});
The libraries send the key as Authorization: Bearer …, which OnVeris accepts for API Keys.
Choosing A Model
The model field of a request names what should answer. It can be:
| Value | Example | Meaning |
|---|---|---|
| A model ID | fp:9189ab12cd34ef56 |
One exact model build. These are the id values from the models list |
| A model name | Qwen3.5-9B |
A model by name |
| An Assistant | assistant:hr-helper |
An Assistant, with its own model, instructions, tools and knowledge |
Use Listing Models to find the values available to you. If your administrator has turned on Only allow assistants, only Assistants will be available.
Content Type
Request and response bodies are JSON (Content-Type: application/json). Streaming responses use Server-Sent Events (text/event-stream).
Errors
Errors are indicated by HTTP status codes, with a body describing the problem. See Errors and Limits.