API Overview

The Queria REST API lets you integrate intelligent document search, AI chat and document management features into any application.

Base URL

All API requests use the following base URL:

https://api.queria.pro

The API uses path-based versioning. Current version is v3.5.0. Public endpoints live under /api/public/, authenticated ones under /api/.

Response format

All responses are in JSON with a consistent structure.

Success response:

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "name": "Supply Contract 2025",
    "status": "VECTORIZED",
    "createdAt": "2026-02-15T10:30:00Z"
  }
}

Paginated response:

{
  "success": true,
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 143,
      "totalPages": 8
    }
  }
}

Error response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'message' is required.",
    "details": [
      { "field": "message", "reason": "Required field" }
    ]
  }
}

HTTP status codes

Code	Meaning	Description
200	OK	Request completed successfully
201	Created	Resource created successfully
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions for the operation
404	Not Found	Resource not found
429	Too Many Requests	Request limit exceeded
500	Internal Server Error	Internal server error

Rate limiting

The API applies frequency limits to ensure stability and performance.

Endpoint type	Limit	Window
Public endpoints	60 requests	1 minute
Authenticated endpoints	300 requests	1 minute
Document upload	10 requests	1 minute
Chat streaming	20 requests	1 minute

Responses include informative rate limit headers:

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

When the limit is exceeded, the API returns a 429 error:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Request limit exceeded. Retry in 23 seconds.",
    "retryAfter": 23
  }
}

Content-Type

All JSON requests must include the header:

Content-Type: application/json

For file uploads, use:

Content-Type: multipart/form-data

Authentication

The API supports two authentication methods:

• JWT Token: for user sessions in web apps. Included via Authorization: Bearer {token} header.
• API Key: for server-to-server integrations and widgets. Included via X-API-Key header.

API Keys follow the format qk_live_* for production and qk_test_* for test environments.

For full details, see the authentication guide.

Quick example

A typical call to the chat API with API Key authentication:

curl -X POST https://api.queria.pro/api/public/chat/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qk_live_abc123def456ghi789" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "What are the main clauses of the contract?",
    "sessionId": "sess_a1b2c3d4"
  }'

Streaming response (Server-Sent Events):

data: {"type":"token","content":"The main"}
data: {"type":"token","content":" clauses of the contract"}
data: {"type":"token","content":" are the following [1]:"}
data: {"type":"sources","sources":[{"id":"doc_8f3a","name":"Supply Contract","score":0.92}]}
data: {"type":"done","citationMap":{"1":{"documentId":"doc_8f3a","chunkId":"chk_001"}}}

Main endpoints

Authentication

Method	Endpoint	Description
POST	/api/auth/login	User login
POST	/api/auth/register	Registration
POST	/api/auth/refresh	Refresh token
POST	/api/auth/logout	Logout

Chat

Method	Endpoint	Description
GET	/api/conversations	List conversations
POST	/api/conversations	New conversation
POST	/api/chat/message	Send message
POST	/api/chat/stream	Chat streaming

Documents

Method	Endpoint	Description
GET	/api/documents	List documents
POST	/api/documents/upload	Upload document
GET	/api/documents/:id	Document details
PUT	/api/documents/:id	Update document
DELETE	/api/documents/:id	Delete document

Topics

Method	Endpoint	Description
GET	/api/topics	List categories
POST	/api/topics	Create category
PUT	/api/topics/:id	Update category
DELETE	/api/topics/:id	Delete category

Companies

Method	Endpoint	Description
GET	/api/companies	List companies
GET	/api/companies/:id	Company details
PUT	/api/companies/:id	Update company

Public APIs (Widget)

Method	Endpoint	Description
POST	/api/public/chat	Non-streaming chat
POST	/api/public/chat/stream	SSE streaming chat
POST	/api/public/search/web	Web search
GET	/api/public/topics	List categories

Pagination

Standard query parameters for lists:

Parameter	Default	Description
page	1	Page number
limit	20	Items per page (max 100)
sort	createdAt	Sort field
order	desc	Direction: asc or desc

Example:

curl -X GET "https://api.queria.pro/api/documents?page=2&limit=50&sort=name&order=asc" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Webhook (Coming Soon)

Notifications for asynchronous events:

• document.uploaded - Document uploaded
• document.vectorized - Processing completed
• document.error - Processing error
• conversation.created - New conversation

SDKs

Official SDKs in development:

• JavaScript / TypeScript
• Python
• PHP

In the meantime, use the REST API directly with any HTTP client.

Next steps

• Authentication - Configure JWT and API Key
• Chat API - Send messages and receive AI responses
• Documents API - Upload and manage documents
• Integrations - Embed Queria into your application