Skip to content

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.