API reference

Rivan exposes a versioned REST API under /api/v1. All endpoints require an authenticated session (cookie) or, for server-to-server calls, a scoped API token. Responses are JSON.

This reference covers the public surface. The agent's /internal/* API is private and not part of the public contract.

Authentication

`` POST /api/v1/auth/login { email, password } → sets session cookie POST /api/v1/auth/refresh → rotates session POST /api/v1/auth/logout → clears session POST /api/v1/auth/register { email, password, companyName } ``

Tickets

`` GET /api/v1/tickets ?status=&cursor= → paginated list GET /api/v1/tickets/{id} → ticket + analysis + proposed reply POST /api/v1/tickets/{id}/reply { content } → send/approve a reply GET /api/v1/tickets/stream → Server-Sent Events of live updates ``

Knowledge base

`` GET /api/v1/kb → list KB entries POST /api/v1/kb { title, content } → add + embed ``

AI config

`` GET /api/v1/ai-config → current model + agent name (no secrets) POST /api/v1/ai-config { apiKey, model, agentName } POST /api/v1/ai-config/test → validate the Anthropic connection ``

Integrations

`` GET /api/v1/integrations → connection status POST /api/v1/integrations/crisp { websiteId, token } → connect Crisp ``

Audit log

`` GET /api/v1/audit-log → owner-only, append-only event history ``

Webhooks (inbound)

`` POST /api/webhooks/crisp → Crisp events (HMAC-verified, deduped) ``

Errors

Errors use standard HTTP status codes with a JSON body:

``json { "error": { "code": "unauthorized", "message": "..." } } ``

| Status | Meaning | |---|---| | 400 | Validation error | | 401 | Not authenticated | | 403 | Authenticated but not allowed (RBAC) | | 404 | Not found / not in your tenant | | 429 | Rate limited |