Connect An OpenAI-Compatible App
Many applications, libraries and automation tools can talk to OpenAI. Most of them can talk to Optima instead, by changing two settings: the address they send requests to, and the key they send. This guide connects one to an Optima Assistant, so the application gets the Assistant's model, instructions, tools and knowledge without knowing about any of them.
In this example we will connect a Python script to HR Helper, the Assistant built in Build an Assistant That Answers From Your Documents. Any Assistant will do.
By the end of this guide you will have a Service Key that can use one Assistant and nothing else, and an application calling it.
Before You Start
You will need the following:
- An Assistant exists. You need the Assistants permission on it.
- You can create API Keys: the API Keys and Certificates permissions (both are needed to open Settings → Security).
- The application's machine can reach the Gateway over HTTPS.
1. Make The Assistant Available To The API
- Open Assistants, select HR Helper, and open its Access tab.
- Under Available in, tick API.
- Click Save.
Note the Assistant's reference, shown in its header: assistant:hr-helper. Click it to copy it. That is what the application will send as its model.
2. Create A Service Key
A Service Key belongs to no person and can do only what you grant it. It is the right kind of key for an application.
- Open Settings → Security and click Manage API Keys.
- Click New Key and choose Service key.
- Enter a Name that says what uses it — for example, Intranet HR widget — and choose a Responsible owner — the person to contact about it.
- Tick the Scopes
chat.completionsandmodels.read. Nothing else is needed to chat with an Assistant. - Click Create, and copy the key. It will be shown only once.
See API Keys.
3. Give The Key Access To The Assistant
A Service Key starts with access to no Assistants, so you must add it to the Assistant's access list.
- Back on HR Helper's Access tab, under Give access, search for the key's name — Intranet HR widget — and add it.
- Click Save.
Warning
Anything holding the key can use everything the Assistant can reach: its Knowledge Bases and its tools. Give a key access only to Assistants it needs.
4. Test With curl
Before configuring the application, check the key and the Assistant work together. Replace the address and key with your own:
curl https://optima.example.com/v1/chat/completions \
-H "Authorization: Bearer optima_sk_…" \
-H "Content-Type: application/json" \
-d '{"model": "assistant:hr-helper", "messages": [{"role": "user", "content": "How many days of annual leave do I get?"}]}'
The reply will be JSON, with the answer in choices[0].message.content. If it is an error instead, see If it does not work.
5. Configure The Application
Whatever the application, look for these settings:
| The application asks for | Enter |
|---|---|
| Base URL, API base, endpoint or OpenAI URL | Your Gateway's address followed by /v1, such as https://optima.example.com/v1 |
| API key | The service key |
| Model | assistant:hr-helper |
Some applications offer a list of models instead of a box. They read it from /v1/models, which lists the Assistants and models the key can use.
Python
For example, with the official openai library:
from openai import OpenAI
client = OpenAI(
base_url="https://optima.example.com/v1",
api_key="optima_sk_…",
)
reply = client.chat.completions.create(
model="assistant:hr-helper",
messages=[{"role": "user", "content": "How many days of annual leave do I get?"}],
)
print(reply.choices[0].message.content)
Node.js
The same request in JavaScript:
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://optima.example.com/v1',
apiKey: 'optima_sk_…',
});
const reply = await client.chat.completions.create({
model: 'assistant:hr-helper',
messages: [{ role: 'user', content: 'How many days of annual leave do I get?' }],
});
console.log(reply.choices[0].message.content);
In practice, keep the key out of the code: read it from an environment variable or the application's secret store.
How The Assistant Behaves On The API
An Assistant called through the API behaves a little differently from one used in Optima Chat:
- Its tools run on the Gateway. When the Assistant uses a tool or searches a Knowledge Base, Optima does the work and returns only the final answer. A streamed response also carries events showing the tool activity, which OpenAI libraries ignore. See Tools the Gateway runs.
- Tools that ask permission are left out. Nobody is there to answer, so an Assistant's ask-first tools are not offered to API callers.
- A system message from the application is added to the Assistant's instructions by default. The Assistant's Behaviour tab can ignore it, use it instead, or refuse the request. See Assistants.
- The application's own tools are offered only if the Assistant allows API callers' own tools, on its Tools tab.
- Nothing is remembered between requests. Like OpenAI's chat completions, each request carries the whole conversation. For the Gateway to keep the history, use
/v1/responses, which needs the key'sresponsesscope too. See Responses.
If Your Gateway Uses Its Own Certificate
If the Gateway's certificate comes from your organisation's own certificate authority, or is the Gateway's self-signed one, the application's machine must trust it. Otherwise every request will fail before it is sent, with a certificate or SSL error.
The best fix is to install the certificate authority on that machine. If you cannot, point the library at the certificate:
Python — give the library an SSL context that trusts it:
import ssl, httpx
from openai import OpenAI
context = ssl.create_default_context(cafile="/path/to/your-ca.pem")
client = OpenAI(
base_url="https://optima.example.com/v1",
api_key="optima_sk_…",
http_client=httpx.Client(verify=context),
)
Node.js — name the certificate when starting the application:
NODE_EXTRA_CA_CERTS=/path/to/your-ca.pem node app.js
Warning
Do not turn certificate checking off: the key would then go to anyone who could intercept the connection. See Certificates and Security.
If It Does Not Work
If a request fails, the response tells you why:
| Response | Cause | Fix |
|---|---|---|
401 |
The key is wrong, revoked or expired, or was not sent | Check the key, and that the application sends it as Authorization: Bearer |
403 naming required_scopes |
The key lacks a scope | Add the named scope to the key, in Manage API Keys → Edit scopes |
404 model_not_found |
The Assistant is not available on the API, or not shared with this key — or the reference is misspelt | Check API is ticked and the key is on the Assistant's Access tab |
503 model_not_available |
None of the Assistant's models are running | Start its model, or give it a fallback |
429 |
The key has hit its rate limit | Slow the application down, or raise the key's Rate limits |
400 context_length_exceeded |
The conversation is too long for the model | Send less history. See Errors and Limits |
| Certificate or SSL error | The machine does not trust the Gateway's certificate | See If your Gateway uses its own certificate |