API Reference

Complete REST API documentation with request/response examples

Base URL

All API endpoints are relative to:

https://api.operativeops.com/v1

Versioning

The API is versioned via URL path. The current version is v1. We will communicate breaking changes well in advance.

Endpoints

POST/v1/conversations

Create Conversation

Start a new conversation with one or more AI agents. Agents will analyze your question using your company's data context.

Request Bodyjson

{
  "question": "Should we expand into the EU market?",
  "agents": ["ceo", "marketing", "analytics"],
  "context": {
    "quarter": "Q2-2026",
    "priority": "growth"
  }
}

Responsejson

{
  "id": "conv_abc123",
  "status": "processing",
  "created_at": "2026-03-25T10:30:00Z",
  "agents": ["ceo", "marketing", "analytics"]
}

GET/v1/conversations/:id

Get Conversation

Retrieve a conversation including all agent responses. Use polling or webhooks to know when agents have responded.

Responsejson

{
  "id": "conv_abc123",
  "status": "completed",
  "responses": [
    {
      "agent": "ceo",
      "name": "Jordan Blake",
      "message": "Based on market analysis, EU expansion is viable..."
    }
  ]
}

POST/v1/agents/ask

Ask Agents

One-shot question to specific agents. Returns immediately with agent responses. Best for simple queries that don't need conversation context.

Request Bodyjson

{
  "question": "What are our biggest risks this quarter?",
  "agents": ["ceo", "cto", "analytics"]
}

Responsejson

{
  "responses": [
    {
      "agent": "ceo",
      "name": "Jordan Blake",
      "message": "Three key risks identified..."
    }
  ]
}

GET/v1/agents

List Agents

List all available agents for your workspace, including their roles, capabilities, and current status.

Responsejson

{
  "agents": [
    {
      "id": "agent_ceo",
      "name": "Jordan Blake",
      "role": "ceo",
      "status": "active"
    }
  ]
}

GET/v1/insights

List Insights

Retrieve proactive insights generated by your AI agents. Insights are automatically generated based on your connected data sources.

Responsejson

{
  "insights": [
    {
      "id": "ins_xyz789",
      "agent": "analytics",
      "title": "Revenue Forecast Update",
      "summary": "Q2 projections revised upward by 12%...",
      "severity": "info",
      "created_at": "2026-03-25T08:00:00Z"
    }
  ]
}

GET/v1/metrics

Get Metrics

Retrieve company metrics and KPIs tracked by your agents. Supports filtering by department, time range, and metric type.

Responsejson

{
  "metrics": [
    {
      "name": "revenue",
      "value": 2450000,
      "change": 0.12,
      "period": "Q1-2026",
      "department": "finance"
    }
  ]
}

Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with details.

400

Bad Request — Invalid parameters or missing required fields

401

Unauthorized — Invalid or missing API key

403

Forbidden — Insufficient permissions for this resource

404

Not Found — Resource does not exist

429

Rate Limited — Too many requests, retry after the specified delay

500

Internal Error — Something went wrong on our end

Rate Limits

API requests are rate limited per API key. Current limits:

Starter: 100 requests/minute, 10,000 requests/day
Enterprise: 1,000 requests/minute, unlimited daily

Getting Started

Webhooks