API Reference

Complete documentation for the Pravia API — integrate AI Employees, manage documents, and configure your bots programmatically.

Base URL: /api/chat (relative)

Authentication

Dashboard (Session Cookie)

Dashboard API calls use your session cookie for authentication. No API key required — just log in.

Widget (Public)

The widget chat endpoint is public and rate-limited. No authentication needed — just the bot ID.

Authorization Header Example

curl -X POST "/api/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "botId": "your-bot-id",
    "query": "Hello!"
  }'

Chat Endpoints

POST/api/chat

Parameter	Type	Required	Description
botId	string	Yes	The unique identifier of your bot.
query	string	Yes	The user's message text (max 2000 characters).
conversationId	string	No	Optional conversation ID for maintaining context across multiple requests.
model	string	No	Override the default model (optional).

Request Example

{
  "botId": "bot_abc123",
  "query": "What is your return policy?",
  "conversationId": "conv_xyz789"
}

Response Example

{
  "conversationId": "conv_xyz789",
  "answer": "Our return policy allows returns within 30 days of purchase.",
  "sources": [
    { "chunkId": "...", "documentId": "...", "content": "...", "score": 0.92 }
  ],
  "offline": false
}

POST/api/widget/chat

Public endpoint for client-side widget usage. Supports botId, query, conversationId, and visitorId. Rate-limited to 10 requests per minute per IP. No authentication required.

Bot Management

GET/api/bots

Retrieve a list of all your bots.

curl -X GET "/api/bots" \
  -H "Content-Type: application/json"

POST/api/bots

Create a new bot with the specified configuration.

Parameter	Type	Required	Description
name	string	Yes	Bot name (1-64 characters).
description	string	No	Optional description of your bot's purpose.
model	string	No	Default model for this bot.

{
  "name": "Support Bot",
  "description": "Answers customer questions based on our knowledge base",
  "model": "pravia"
}

Document Management

GET/api/documents

Retrieve all documents for a specific bot.

Parameter	Type	Required	Description
botId	string	Yes	Filter documents by bot.

POST/api/documents

Add knowledge sources to a bot. Supports: file upload (PDF, Markdown, DOCX, TXT), URL extraction (Website), Sitemap XML import, or raw text. Use multipart/form-data for files, or JSON for URL/text/sitemap.

Rate Limits

Endpoint	Rate Limit
Widget Chat (/api/widget/chat)	10 req/min per IP
Dashboard API (/api/chat, /api/bots, /api/documents)	30 req/min per user

Error Responses

Code	HTTP Status	Description
400	400	Bad request. Returns a string error message like 'botId is required', 'query is required', or 'Query too long'.
401	401	Unauthorized. Session cookie missing or invalid.
403	403	Forbidden. Billing limit reached or access denied.
404	404	Not found. Bot not found or inactive.
503	503	Service temporarily unavailable. Billing limit exceeded.
500	500	Internal server error.

Endpoint Summary

Method	Endpoint	Auth	Description
POST	/api/chat	Session	Send a message to a bot and receive an AI-generated reply.
POST	/api/widget/chat	Public	Send a message from the widget with rate limiting.
GET	/api/bots	Session	List all bots in your account.
POST	/api/bots	Session	Create a new bot.
GET	/api/bots/:id	Session	Retrieve a single bot by ID.
GET	/api/documents	Session	List documents for a bot.
POST	/api/documents	Session	Upload a document to a bot.

Ready to integrate?

View Documentation Start Free