Vorena AI API Reference

Use the Vorena public API to integrate your conversations, contacts, pipelines, knowledge base, and analytics with external systems.

OpenAPI spec available at /api/v1/openapi

Authentication

All API requests require a valid API key sent via the Authorization header. API keys can be created from Settings → API Keys in your dashboard.

Authorization: Bearer vk_live_your_api_key_here

Rate Limits

API requests are limited to 20 requests per minute per API key. Exceeding this limit returns a 429 status code.

Quick Start

const response = await fetch("https://vorena-ai.com/api/v1/contacts", {
  headers: {
    "Authorization": "Bearer vk_live_your_api_key_here",
    "Content-Type": "application/json",
  },
});

const { data, pagination } = await response.json();
console.log(data); // Array of contacts

Account

GET/api/v1/me

Returns the authenticated client's ID and business name. Used by plugins for verification.

Required scope: (any valid key)

Response:

{ "clientId": "uuid", "businessName": "Apex Fitness Studio" }

Contacts

GET/api/v1/contacts

List contacts (leads) for your account.

Required scope: contacts:read

Query parameters:

page (default: 1), limit (default: 20, max: 100)

Response:

{
  "data": [{ "id": "uuid", "name": "Jane Smith", "email": "jane@example.com", "status": "new", ... }],
  "pagination": { "page": 1, "limit": 20, "total": 128 }
}

POST/api/v1/contacts

Create a new contact. Requires name and email.

Required scope: contacts:write

Request body:

{ "name": "Jane Smith", "email": "jane@example.com", "phone": "+15551234567", "source": "api" }

Response:

// 201 Created
{ "data": { "id": "uuid", "name": "Jane Smith", "email": "jane@example.com", "status": "new", ... } }

GET/api/v1/contacts/:id

Get a single contact by ID.

Required scope: contacts:read

Response:

{ "data": { "id": "uuid", "name": "Jane Smith", "email": "jane@example.com", "form_data": {...}, ... } }

PUT/api/v1/contacts/:id

Update a contact's name, email, phone, or status.

Required scope: contacts:write

Request body:

{ "name": "Jane Doe", "status": "qualified" }

Response:

{ "data": { "id": "uuid", "name": "Jane Doe", "status": "qualified", ... } }

DELETE/api/v1/contacts/:id

Delete a contact.

Required scope: contacts:write

Response:

{ "success": true }

Conversations

GET/api/v1/conversations

List conversations for your account.

Required scope: conversations:read

Query parameters:

page (default: 1), limit (default: 20, max: 100)

Response:

{
  "data": [{ "id": "uuid", "visitor_id": "visitor-123", "status": "active", "started_at": "2026-01-15T10:30:00Z", ... }],
  "pagination": { "page": 1, "limit": 20, "total": 42 }
}

POST/api/v1/conversations

Create a new conversation.

Required scope: conversations:write

Request body:

{ "visitor_id": "visitor-456", "metadata": { "source": "api" } }

Response:

// 201 Created
{ "data": { "id": "uuid", "visitor_id": "visitor-456", "status": "active", ... } }

GET/api/v1/conversations/:id

Get a single conversation with escalation details.

Required scope: conversations:read

Response:

{ "data": { "id": "uuid", "escalated": false, "escalated_reason": null, ... } }

GET/api/v1/conversations/:id/messages

List messages within a conversation.

Required scope: conversations:read

Query parameters:

page (default: 1), limit (default: 20, max: 100)

Response:

{
  "data": [{ "id": "uuid", "role": "user", "content": "Hello!", "created_at": "..." }],
  "pagination": { "page": 1, "limit": 20, "total": 15 }
}

POST/api/v1/conversations/:id/messages

Add a message to a conversation. Role must be user, assistant, or admin.

Required scope: conversations:write

Request body:

{ "role": "admin", "content": "A human agent has joined the chat." }

Response:

// 201 Created
{ "data": { "id": "uuid", "role": "admin", "content": "A human agent has joined the chat.", ... } }

Pipelines

GET/api/v1/pipelines

List pipelines for your account, including row counts.

Required scope: pipelines:read

Response:

{
  "data": [{ "id": "uuid", "name": "Sales Pipeline", "stages": ["Lead", "Qualified", "Closed"], "row_count": 34, ... }]
}

GET/api/v1/pipelines/:id

Get a single pipeline with its column definitions.

Required scope: pipelines:read

Response:

{ "data": { "id": "uuid", "name": "Sales Pipeline", "columns": [...], "row_count": 34, ... } }

GET/api/v1/pipelines/:id/rows

List rows in a pipeline.

Required scope: pipelines:read

Query parameters:

page (default: 1), limit (default: 20, max: 100)

Response:

{
  "data": [{ "id": "uuid", "data": { "name": "Acme Corp", "stage": "Qualified" }, "source_type": "api", ... }],
  "pagination": { "page": 1, "limit": 20, "total": 34 }
}

POST/api/v1/pipelines/:id/rows

Create a new row in a pipeline.

Required scope: pipelines:write

Request body:

{ "data": { "name": "Acme Corp", "stage": "Lead", "value": 5000 }, "source_ref": "crm-123" }

Response:

// 201 Created
{ "data": { "id": "uuid", "data": { "name": "Acme Corp", ... }, "source_type": "api", ... } }

PUT/api/v1/pipelines/:id/rows/:rowId

Update a pipeline row. Set merge=true to merge with existing data instead of replacing.

Required scope: pipelines:write

Request body:

{ "data": { "stage": "Closed", "value": 7500 }, "merge": true }

Response:

{ "data": { "id": "uuid", "data": { "name": "Acme Corp", "stage": "Closed", "value": 7500 }, ... } }

DELETE/api/v1/pipelines/:id/rows/:rowId

Delete a pipeline row.

Required scope: pipelines:write

Response:

{ "success": true }

Knowledge Base

GET/api/v1/knowledge

List knowledge base documents.

Required scope: knowledge:read

Query parameters:

page (default: 1), limit (default: 20, max: 100)

Response:

{
  "data": [{ "id": "uuid", "title": "FAQs", "type": "faq", "status": "processed", "chunk_count": 12, ... }],
  "pagination": { "page": 1, "limit": 20, "total": 5 }
}

POST/api/v1/knowledge

Add a text-based knowledge document. Type can be text, faq, or url.

Required scope: knowledge:write

Request body:

{ "title": "Return Policy", "content": "We offer 30-day returns...", "type": "text" }

Response:

// 201 Created
{ "data": { "id": "uuid", "title": "Return Policy", "type": "text", "status": "pending", ... } }

DELETE/api/v1/knowledge?id=:id

Delete a knowledge document by ID (pass as query parameter).

Required scope: knowledge:write

Response:

{ "success": true }

Analytics

GET/api/v1/analytics

Get conversation and lead analytics summary.

Required scope: analytics:read

Query parameters:

period: 7d | 30d | 90d (default: 30d)

Response:

{
  "data": {
    "period": "30d",
    "conversations": { "total": 342, "period": 87, "escalated": 3 },
    "leads": { "total": 128, "period": 31, "hot": 8, "warm": 15, "cold": 105 }
  }
}

Error Codes

Status	Meaning
400	Invalid request body or parameters
401	Invalid or missing API key
403	API key lacks the required scope
404	Resource not found or does not belong to your account
429	Rate limit exceeded (20 requests/minute)
500	Internal server error

Webhooks

Configure webhooks in Dashboard → Integrations → Webhooks to receive real-time event notifications. Available on Elite and Enterprise plans.

Event	Fired when
lead.created	New lead captured via widget or API
lead.scored	Lead score changes (hot/warm/cold)
followup.sent	Follow-up email or SMS sent
conversation.escalated	Conversation escalated to human agent
row.created	Pipeline row created
row.updated	Pipeline row updated
row.deleted	Pipeline row deleted
rule.triggered	Automation rule triggered

Every webhook includes an X-Vorena-Signature HMAC-SHA256 header for verification. Failed deliveries retry up to 3 times with exponential backoff.