What’s newRelease 10 · Oct 23, 2026Ask Ollive in natural languageRead the changelog

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

  1. 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.

  2. 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_…"
  3. List the agents Ollive monitors

    This request returns your agents. Each one has an id, which the other endpoints call agent_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  }'
  4. See what Ollive found

    Pass an agent_id to List findings to see which rules the agent didn’t meet. To see why a run was flagged, use List results.

Key terms

AgentAn agent Ollive monitors. Its ID is the agent_id.
RunOne conversation between your agent and a person. You give it an ID, the run_id.
RuleSomething your agent must or must not do, such as identifying itself as automated. Its ID is the rule_id.
Rule setA set of rules an agent is checked against, drawn from a regulation, a framework or a contract.
ResultThe result of checking one rule in one run: met, not_met or inconclusive.
FindingOne agent not meeting one rule, across one or more runs.

Endpoints

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.

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/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>"}'

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.