API Reference

Complete REST API documentation for the Operanix platform. All endpoints require authentication and are scoped to your tenant.

Authentication

All API requests must include a valid authentication credential. Operanix supports two methods:

Bearer Token (recommended)

Include a Firebase ID token in the Authorization header:

Authorization: Bearer <firebase-id-token>

API Key

For server-to-server integrations, pass your API key via the x-api-key header:

x-api-key: opx_live_abc123...

Base URL

https://api.operanix.ai/v1

All request and response bodies use JSON. Set Content-Type: application/json on all requests with a body.

Rate Limits

Rate limits are enforced per tenant using a token-bucket algorithm. Limits vary by plan tier:

Plan	Requests/min	Chat messages/min	Pipeline runs/day	Burst
Starter	60	20	5	2x for 10s
Professional	300	100	50	3x for 10s
Enterprise	1,200	500	Unlimited	5x for 30s

Rate limit status is returned in response headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1718640000

1. Authentication

POST/api/auth/register— Register a new user account

POST/api/auth/login— Authenticate and receive tokens

POST/api/auth/refresh— Refresh an expired access token

POST/api/auth/logout— Revoke the current session

2. Enterprise Chat

POST/api/chat/message— Send a message to an agent

POST/api/chat/stream— Stream a response (SSE)

GET/api/chat/conversations— List conversations for the current user

GET/api/chat/conversations/:id— Get a single conversation with messages

GET/api/chat/conversations/:id/messages— List messages in a conversation

PATCH/api/chat/conversations/:id— Update conversation title or metadata

DELETE/api/chat/conversations/:id— Delete a conversation

POST/api/chat/conversations/:id/feedback— Submit feedback on a response

3. Multi-Agent Collaboration

POST/api/collaborate/sessions— Create a multi-agent collaboration session

GET/api/collaborate/sessions— List active collaboration sessions

GET/api/collaborate/sessions/:id— Get session details and participant agents

POST/api/collaborate/sessions/:id/message— Send a message to the collaboration

POST/api/collaborate/sessions/:id/agents— Add an agent to the session

DELETE/api/collaborate/sessions/:id/agents/:agentId— Remove an agent from the session

POST/api/collaborate/sessions/:id/close— Close and archive the session

4. Agent Deployment

GET/api/agents— List all agents for the tenant

GET/api/agents/:id— Get agent configuration and status

POST/api/agents— Create a new agent

PATCH/api/agents/:id— Update agent identity, prompts, or tools

POST/api/agents/:id/deploy— Deploy agent to production

POST/api/agents/:id/pause— Pause a deployed agent

DELETE/api/agents/:id— Delete an agent and its configuration

5. Governance Intelligence

GET/api/governance/policies— List all governance policies

POST/api/governance/policies— Create a governance policy

PATCH/api/governance/policies/:id— Update a policy's rules or thresholds

GET/api/governance/approvals— List pending approval requests

POST/api/governance/approvals/:id/approve— Approve a pending action

POST/api/governance/approvals/:id/reject— Reject a pending action with reason

6. Experiment Intelligence

GET/api/experiments— List all experiments

POST/api/experiments— Create an A/B experiment

GET/api/experiments/:id— Get experiment details and metrics

PATCH/api/experiments/:id— Update experiment configuration

POST/api/experiments/:id/start— Start running the experiment

POST/api/experiments/:id/stop— Stop and finalize results

GET/api/experiments/:id/results— Get statistical results and winner

7. Feedback Intelligence

GET/api/feedback— List all feedback entries

POST/api/feedback— Submit feedback on an agent response

GET/api/feedback/summary— Get aggregated feedback metrics

GET/api/feedback/agents/:agentId— Get feedback for a specific agent

GET/api/feedback/trends— Get feedback trends over time

DELETE/api/feedback/:id— Delete a feedback entry

8. Marketplace Intelligence

GET/api/marketplace/templates— Browse available agent templates

GET/api/marketplace/templates/:id— Get template details and reviews

POST/api/marketplace/templates/:id/install— Install a template to your tenant

POST/api/marketplace/publish— Publish a custom template

GET/api/marketplace/categories— List marketplace categories

POST/api/marketplace/templates/:id/review— Submit a review for a template

GET/api/marketplace/installed— List templates installed in your tenant

9. Notifications

GET/api/notifications— List notifications for the current user

GET/api/notifications/unread-count— Get count of unread notifications

PATCH/api/notifications/:id/read— Mark a notification as read

POST/api/notifications/read-all— Mark all notifications as read

GET/api/notifications/preferences— Get notification preferences

PATCH/api/notifications/preferences— Update notification preferences

10. Usage & Cost

GET/api/usage/summary— Get current billing period usage summary

GET/api/usage/daily— Get daily usage breakdown

GET/api/usage/by-agent— Get usage breakdown by agent

GET/api/usage/costs— Get cost breakdown by LLM provider

GET/api/usage/export— Export usage data as CSV

11. Webhook Events

GET/api/webhooks— List configured webhooks

POST/api/webhooks— Create a webhook subscription

GET/api/webhooks/:id— Get webhook configuration and delivery log

PATCH/api/webhooks/:id— Update webhook URL, events, or secret

DELETE/api/webhooks/:id— Delete a webhook subscription

POST/api/webhooks/:id/test— Send a test event to the webhook

12. White-Label

GET/api/whitelabel/config— Get white-label branding configuration

PATCH/api/whitelabel/config— Update branding (logo, colors, domain)

POST/api/whitelabel/config/logo— Upload a custom logo

GET/api/whitelabel/domain— Get custom domain configuration

POST/api/whitelabel/domain— Configure a custom domain

POST/api/whitelabel/domain/verify— Verify DNS for custom domain

13. Knowledge Pipeline

GET/api/knowledge/sources— List all knowledge sources

POST/api/knowledge/sources— Add a knowledge source (URL, file, API)

GET/api/knowledge/sources/:id— Get source details and crawl status

PATCH/api/knowledge/sources/:id— Update source configuration

DELETE/api/knowledge/sources/:id— Remove a knowledge source

POST/api/knowledge/sources/:id/crawl— Trigger an immediate crawl

GET/api/knowledge/entities— List structured entities

POST/api/knowledge/entities— Create a structured entity

GET/api/knowledge/entities/:id— Get entity with relationships

PATCH/api/knowledge/entities/:id— Update entity fields or metadata

DELETE/api/knowledge/entities/:id— Delete an entity

GET/api/knowledge/chunks— List document chunks

GET/api/knowledge/chunks/:id— Get chunk content and embedding metadata

POST/api/knowledge/search— Semantic search across knowledge base

GET/api/knowledge/pipeline/status— Get current pipeline run status

POST/api/knowledge/pipeline/run— Trigger a full pipeline run

GET/api/knowledge/pipeline/history— List past pipeline runs

GET/api/knowledge/pipeline/runs/:id— Get detailed run report

GET/api/knowledge/stats— Get knowledge base statistics

POST/api/knowledge/upload— Upload a document file

GET/api/knowledge/versions— List published knowledge versions

POST/api/knowledge/publish— Publish current knowledge as a version

14. Trust Dashboard

GET/api/trust/scores— Get trust scores for all agents

GET/api/trust/scores/:agentId— Get detailed trust breakdown for an agent

Error Responses

All errors follow a consistent JSON format:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Retry after 12 seconds.",
    "status": 429,
    "retryAfter": 12
  }
}

Status	Code	Description
`400`	VALIDATION_ERROR	Request body failed schema validation
`401`	UNAUTHORIZED	Missing or invalid authentication credential
`403`	FORBIDDEN	Authenticated but insufficient permissions
`404`	NOT_FOUND	Resource does not exist in your tenant
`409`	CONFLICT	Resource already exists or concurrent modification
`429`	RATE_LIMIT_EXCEEDED	Too many requests, retry after the specified delay
`500`	INTERNAL_ERROR	Unexpected server error, contact support
`503`	SERVICE_UNAVAILABLE	LLM provider temporarily unavailable

Need help integrating? See the Quickstart Guide for a step-by-step walkthrough, or explore the Architecture docs to understand the full platform.