Documentation API Reference

API Reference

Complete reference for the Cevvo REST API.

Base URL

https://prod-backend-api.cevvo.ai/api/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request header.

Header Parameters

Authorizationstringrequired

Bearer token using your API key

Generate API keys from the API Keys page in your dashboard.

Example Request

curl --request GET \
  --url 'https://prod-backend-api.cevvo.ai/api/v1/sources' \
  --header 'Authorization: Bearer YOUR_API_KEY'

SDKs

Official client libraries to integrate Cevvo into your application.

JavaScript / TypeScript

@cevvo/sdk

Install

npm install @cevvo/sdk

Python

cevvo-sdk

Install

pip install cevvo-sdk

Go

cevvo-go

Install

go get github.com/cevvo/cevvo-go

cURL

REST API

Install

# No installation needed

Chat

Send messages and manage conversations.

POST/chat

Send a message and get an AI-generated response based on your knowledge base.

Body Parameters

messagestring required

The user message to send.

thread_idstring

Conversation thread ID for context continuity.

modelstring default:auto

Model to use for generation (auto, gpt-4o, claude-sonnet-4-20250514).

curl --request POST \
  --url 'https://api.cevvo.com/api/v1/chat' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "message": "How do I get started?",
    "thread_id": null
  }'

200Response

{
  "id": "msg_abc123",
  "answer": "To get started with Cevvo, first create a source...",
  "thread_id": "thr_xyz789",
  "sources": [
    {
      "title": "Getting Started Guide",
      "url": "https://docs.example.com/getting-started",
      "score": 0.95
    }
  ],
  "model": "gpt-4o",
  "usage": {
    "prompt_tokens": 512,
    "completion_tokens": 128
  }
}

POST/chat/stream

Send a message and receive a streaming response using Server-Sent Events (SSE).

Body Parameters

messagestring required

The user message to send.

thread_idstring

Conversation thread ID for context continuity.

curl --request POST \
  --url 'https://api.cevvo.com/api/v1/chat/stream' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "message": "Explain the main features"
  }'

200Response

data: {"type": "text", "text": "To get "}
data: {"type": "text", "text": "started "}
data: {"type": "text", "text": "with Cevvo..."}
data: {"type": "sources", "sources": [...]}
data: [DONE]

Conversations

Manage conversation threads and history.

GET/conversations

List all conversations with pagination support.

Query Parameters

pageinteger default:1

Page number for pagination.

per_pageinteger default:20

Number of items per page (max 100).

curl --request GET \
  --url 'https://api.cevvo.com/api/v1/conversations?page=1&per_page=20' \
  --header 'Authorization: Bearer YOUR_API_KEY'

200Response

{
  "data": [
    {
      "id": "thr_xyz789",
      "title": "Getting started help",
      "message_count": 4,
      "created_at": "2026-03-10T14:30:00Z",
      "updated_at": "2026-03-10T14:35:22Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 42
  }
}

GET/conversations/:id

Get a specific conversation with all messages.

Path Parameters

idstring required

The conversation thread ID.

curl --request GET \
  --url 'https://api.cevvo.com/api/v1/conversations/thr_xyz789' \
  --header 'Authorization: Bearer YOUR_API_KEY'

200Response

{
  "id": "thr_xyz789",
  "title": "Getting started help",
  "messages": [
    {
      "role": "user",
      "content": "How do I get started?",
      "created_at": "2026-03-10T14:30:00Z"
    },
    {
      "role": "assistant",
      "content": "To get started with Cevvo...",
      "sources": [...],
      "created_at": "2026-03-10T14:30:02Z"
    }
  ],
  "created_at": "2026-03-10T14:30:00Z"
}

DELETE/conversations/:id

Delete a conversation and all its messages.

Path Parameters

idstring required

The conversation thread ID to delete.

curl --request DELETE \
  --url 'https://api.cevvo.com/api/v1/conversations/thr_xyz789' \
  --header 'Authorization: Bearer YOUR_API_KEY'

200Response

{
  "deleted": true
}

Sources

Manage knowledge base sources.

GET/sources

List all knowledge base sources.

Query Parameters

pageinteger default:1

Page number for pagination.

per_pageinteger default:20

Number of items per page.

typestring

Filter by source type (website, file, text).

curl --request GET \
  --url 'https://api.cevvo.com/api/v1/sources' \
  --header 'Authorization: Bearer YOUR_API_KEY'

200Response

{
  "data": [
    {
      "id": "src_abc123",
      "name": "Product Documentation",
      "type": "website",
      "url": "https://docs.example.com",
      "status": "synced",
      "document_count": 156,
      "last_synced_at": "2026-03-10T12:00:00Z",
      "created_at": "2026-02-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 5
  }
}

POST/sources

Create a new knowledge base source.

Body Parameters

namestring required

Display name for the source.

typestring required

Source type: website, file, or text.

urlstring

URL to crawl (required for website type).

auto_syncboolean default:false

Enable automatic syncing on a schedule.

curl --request POST \
  --url 'https://api.cevvo.com/api/v1/sources' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Product Docs",
    "type": "website",
    "url": "https://docs.example.com",
    "auto_sync": true
  }'

201Response

{
  "id": "src_def456",
  "name": "Product Docs",
  "type": "website",
  "url": "https://docs.example.com",
  "status": "pending",
  "auto_sync": true,
  "created_at": "2026-03-14T10:00:00Z"
}

GET/sources/:id

Get details for a specific source.

Path Parameters

idstring required

The source ID.

curl --request GET \
  --url 'https://api.cevvo.com/api/v1/sources/src_abc123' \
  --header 'Authorization: Bearer YOUR_API_KEY'

200Response

{
  "id": "src_abc123",
  "name": "Product Documentation",
  "type": "website",
  "url": "https://docs.example.com",
  "status": "synced",
  "document_count": 156,
  "auto_sync": true,
  "last_synced_at": "2026-03-10T12:00:00Z",
  "created_at": "2026-02-15T10:00:00Z"
}

PUT/sources/:id

Update an existing source.

Body Parameters

namestring

Updated display name.

auto_syncboolean

Enable or disable auto sync.

curl --request PUT \
  --url 'https://api.cevvo.com/api/v1/sources/src_abc123' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Docs",
    "auto_sync": false
  }'

200Response

{
  "id": "src_abc123",
  "name": "Updated Docs",
  "type": "website",
  "auto_sync": false,
  "updated_at": "2026-03-14T11:00:00Z"
}

DELETE/sources/:id

Delete a source and all its ingested documents.

Path Parameters

idstring required

The source ID to delete.

curl --request DELETE \
  --url 'https://api.cevvo.com/api/v1/sources/src_abc123' \
  --header 'Authorization: Bearer YOUR_API_KEY'

200Response

{
  "deleted": true
}

Ingestion

Ingest and manage documents.

POST/ingest/upload

Upload and ingest a document file (PDF, DOCX, TXT, MD).

Body Parameters

filefile required

The document file to upload.

source_idstring required

The source to ingest the document into.

curl --request POST \
  --url 'https://api.cevvo.com/api/v1/ingest/upload' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --form 'file=@document.pdf' \
  --form 'source_id=src_abc123'

202Response

{
  "job_id": "job_ing_001",
  "status": "processing",
  "file_name": "document.pdf",
  "source_id": "src_abc123"
}

POST/ingest/url

Ingest content from a URL.

Body Parameters

urlstring required

The URL to fetch and ingest.

source_idstring required

The source to ingest into.

curl --request POST \
  --url 'https://api.cevvo.com/api/v1/ingest/url' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/guide",
    "source_id": "src_abc123"
  }'

202Response

{
  "job_id": "job_ing_002",
  "status": "processing",
  "url": "https://example.com/guide",
  "source_id": "src_abc123"
}

GET/ingest/status/:id

Check the status of an ingestion job.

Path Parameters

idstring required

The ingestion job ID.

curl --request GET \
  --url 'https://api.cevvo.com/api/v1/ingest/status/job_ing_001' \
  --header 'Authorization: Bearer YOUR_API_KEY'

200Response

{
  "job_id": "job_ing_001",
  "status": "completed",
  "documents_processed": 24,
  "started_at": "2026-03-14T10:00:00Z",
  "completed_at": "2026-03-14T10:02:15Z"
}

Analytics

Access analytics and insights.

GET/analytics/overview

Get dashboard overview metrics including total conversations, resolution rate, and response time.

Query Parameters

periodstring default:7d

Time period: 24h, 7d, 30d, 90d.

curl --request GET \
  --url 'https://api.cevvo.com/api/v1/analytics/overview?period=7d' \
  --header 'Authorization: Bearer YOUR_API_KEY'

200Response

{
  "total_conversations": 1247,
  "resolution_rate": 0.89,
  "avg_response_time_ms": 1250,
  "total_messages": 4821,
  "period": "7d",
  "trend": {
    "conversations": 0.12,
    "resolution_rate": 0.03
  }
}

GET/analytics/top-questions

Get the most frequently asked questions.

Query Parameters

limitinteger default:10

Number of questions to return (max 50).

periodstring default:7d

Time period: 24h, 7d, 30d, 90d.

curl --request GET \
  --url 'https://api.cevvo.com/api/v1/analytics/top-questions?limit=10' \
  --header 'Authorization: Bearer YOUR_API_KEY'

200Response

{
  "data": [
    {
      "question": "How do I get started?",
      "count": 89,
      "resolved_rate": 0.95
    },
    {
      "question": "What pricing plans are available?",
      "count": 67,
      "resolved_rate": 0.88
    }
  ]
}

GET/analytics/coverage-gaps

Get questions that could not be answered from the knowledge base.

Query Parameters

limitinteger default:10

Number of gaps to return.

periodstring default:7d

Time period: 24h, 7d, 30d, 90d.

curl --request GET \
  --url 'https://api.cevvo.com/api/v1/analytics/coverage-gaps?limit=10' \
  --header 'Authorization: Bearer YOUR_API_KEY'

200Response

{
  "data": [
    {
      "question": "Do you support SSO?",
      "count": 23,
      "first_asked": "2026-03-08T09:15:00Z"
    }
  ]
}

Rate Limits

API requests are limited to 100 requests per minute per API key. Exceeding this limit will result in a 429 Too Many Requests response.