API reference

The Ollive API.
Your agents’ record, in code.

Connect your platforms, send conversations, and read what Ollive found: which rules your agents broke, why, and how often.

Base URL: https://api.ollive.ai/api
Authentication: Authorization: Bearer sk-…
Format: JSON over HTTPS

Make your first request

Create an API key
In Ollive, go to Admin → API keys and create a key. It is shown only once, so copy it before you close the window. More about keys.
Save it as an environment variable
Keep the key on your server, never in code that runs in a browser or an app.
Terminal
```
export OLLIVE_API_KEY="sk-…"
```

List the agents Ollive monitors

This request returns your deployments. Each one has an id, which the other endpoints call deployment_id.

curl -X POST "https://api.ollive.ai/api/deployments/query/v1" \  -H "Authorization: Bearer $OLLIVE_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "status": "active",    "limit": 10  }'

import osimport requests response = requests.post(    "https://api.ollive.ai/api/deployments/query/v1",    headers={"Authorization": f"Bearer {os.environ['OLLIVE_API_KEY']}"},    json={        "status": "active",        "limit": 10    },    timeout=30,)response.raise_for_status()print(response.json())

const response = await fetch("https://api.ollive.ai/api/deployments/query/v1", {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.OLLIVE_API_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    "status": "active",    "limit": 10  }),}); if (!response.ok) throw new Error(`Ollive API ${response.status}`);const data = await response.json();

See what Ollive found
Pass a deployment_id to List violations to see which rules the agent broke. To see why a conversation failed, use List verdicts.

Key terms

Deployment	An agent Ollive monitors. Its ID is the `deployment_id`.
Session	One conversation between your agent and a person. You give it an ID, the `session_ref`.
Rule	Something your agent must or must not do, such as identifying itself as automated. In the API, a rule is a `directive`.
Source	The law, regulation or contract a rule comes from. In the API, a `binding_text`.
Rule pack	A set of rules an agent is checked against.
Verdict	The result of checking one rule in one conversation: `pass`, `fail` or `indeterminate`.
Violation	One agent breaking one rule, across one or more conversations.

Endpoints

Integrations

Connect the platforms your agents run on, and see the agents Ollive finds there.

Deployments

A deployment is an agent Ollive monitors. Its ID is the deployment_id you pass to the sessions and monitoring endpoints.

Sessions

Send conversations from your own agents for Ollive to check, then follow their progress and read their transcripts.

Monitoring

See which rules your agents broke, why, and how often.

How requests work

Every endpoint uses POST with a JSON body, even when it only reads data. IDs go in the body, not in the URL.
Your API key decides which account you are working in, so you never send an account ID.
Send only the fields an endpoint lists. Any other field returns a 400.
Times are in UTC, written like 2026-10-14T09:00:00Z.
If nothing matches what you asked for, you get an empty list, not an error.
Endpoints marked Safe to retry don’t change anything, so you can send them again at any time.
Every response has an X-Request-Id header. Include it if you contact support.

Pagination

Endpoints that can return long lists send results one page at a time. Use limit to set the page size. If the response has has_more: true, send the same request again with cursor set to the next_cursor you got back. On the last page, next_cursor is empty.

# First pagecurl -X POST "https://api.ollive.ai/api/sessions/query/v1" \  -H "Authorization: Bearer $OLLIVE_API_KEY" \  -d '{"since": "7d", "limit": 100}' # Next pages: send the next_cursor you got back as cursorcurl -X POST "https://api.ollive.ai/api/sessions/query/v1" \  -H "Authorization: Bearer $OLLIVE_API_KEY" \  -d '{"since": "7d", "limit": 100, "cursor": "<next_cursor>"}'

import osimport requests def all_sessions(**filters):    body = {"limit": 100, **filters}    while True:        page = requests.post(            "https://api.ollive.ai/api/sessions/query/v1",            headers={"Authorization": f"Bearer {os.environ['OLLIVE_API_KEY']}"},            json=body,            timeout=30,        ).json()        yield from page["data"]        if not page["has_more"]:            return        body["cursor"] = page["next_cursor"] for session in all_sessions(since="7d"):    print(session["session_ref"], session["fail_count"])

async function* allSessions(filters = {}) {  const body = { limit: 100, ...filters };  while (true) {    const res = await fetch("https://api.ollive.ai/api/sessions/query/v1", {      method: 'POST',      headers: { Authorization: `Bearer ${process.env.OLLIVE_API_KEY}` },      body: JSON.stringify(body),    });    const page = await res.json();    yield* page.data;    if (!page.has_more) return;    body.cursor = page.next_cursor;  }} for await (const session of allSessions({ since: '7d' })) {  console.log(session.session_ref, session.fail_count);}

Where conversations come from

Each conversation has a source: PLATFORM if Ollive collected it from a connected platform, or API if you sent it with Send sessions.

Violations and metrics count the conversations Ollive collected. To count the ones you sent instead, set source to API. Sessions, verdicts and transcripts include both.