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 ollive_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="ollive_sk_…" - List the agents Ollive monitors
This request returns your agents. Each one has an
id, which the other endpoints callagent_id.curl -X POST "https://api.ollive.ai/api/agents/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/agents/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/agents/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 an
agent_idto List findings to see which rules the agent didn’t meet. To see why a run was flagged, use List results.
Key terms
| Agent | An agent Ollive monitors. Its ID is the agent_id. |
|---|---|
| Run | One conversation between your agent and a person. You give it an ID, the run_id. |
| Rule | Something your agent must or must not do, such as identifying itself as automated. Its ID is the rule_id. |
| Rule set | A set of rules an agent is checked against, drawn from a regulation, a framework or a contract. |
| Result | The result of checking one rule in one run: met, not_met or inconclusive. |
| Finding | One agent not meeting one rule, across one or more runs. |
Endpoints
Integrations
Connect the platforms your agents run on, and see the agents Ollive finds there.
- POSTList integration types/integration-types/query/v1
- POSTList integrations/integrations/query/v1
- POSTCreate an integration/integrations/create/v1
- POSTUpdate an integration/integrations/update/v1
- POSTDelete an integration/integrations/delete/v1
- POSTTest an integration/integrations/test/v1
- POSTSync an integration/integrations/sync/v1
- POSTList assets/integration-assets/query/v1
Agents
An agent is one Ollive monitors. Its ID is the agent_id you pass to the runs and monitoring endpoints.
Runs
A run is one conversation of one agent. Send runs from your own agents for Ollive to check, then follow their progress and read their transcripts.
Monitoring
See which rules your agents didn’t meet, why, and how often.
How requests work
- Every endpoint uses
POSTwith 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-Idheader. 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/runs/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/runs/query/v1" \ -H "Authorization: Bearer $OLLIVE_API_KEY" \ -d '{"since": "7d", "limit": 100, "cursor": "<next_cursor>"}'import osimport requests def all_runs(**filters): body = {"limit": 100, **filters} while True: page = requests.post( "https://api.ollive.ai/api/runs/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 run in all_runs(since="7d"): print(run["run_id"], run["not_met_count"])async function* allRuns(filters = {}) { const body = { limit: 100, ...filters }; while (true) { const res = await fetch("https://api.ollive.ai/api/runs/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 run of allRuns({ since: '7d' })) { console.log(run.run_id, run.not_met_count);}
Where runs come from
Each run has a source: platform if Ollive collected it from a connected platform, api if you sent it with Send runs, or mcp if your AI assistant sent it.
Findings and metrics count the runs Ollive collected. To count the ones you sent instead, set source to api or mcp. Runs, results and transcripts include all of them.