Documents API

The Documents API lets you upload, manage and query documents indexed in the platform. Every document goes through an automatic processing pipeline that makes it available for semantic search.

Upload

Single upload

POST /api/documents/upload
Content-Type: multipart/form-data

Field	Type	Required	Description
file	File	Yes	Document to upload
topicId	string	No	Destination category
description	string	No	Document description
confidentiality	string	No	Level: public, internal, confidential

Example:

curl -X POST https://api.queria.pro/api/documents/upload \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "file=@supply_contract.pdf" \
  -F "topicId=topic_123" \
  -F "description=Annual contract supplier ABC" \
  -F "confidentiality=internal"

Response:

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "name": "supply_contract.pdf",
    "mimeType": "application/pdf",
    "size": 2458624,
    "status": "UPLOADED",
    "topicId": "topic_123",
    "message": "Document uploaded, processing started",
    "createdAt": "2026-03-04T10:30:00Z"
  }
}

Multiple upload

POST /api/documents/upload-multiple
Content-Type: multipart/form-data

Supports up to 10 files at once. Each file is processed in parallel.

Field	Type	Description
files[]	File[]	Document array (max 10)
topicId	string	Common category for all files

Response:

{
  "success": true,
  "data": {
    "uploaded": 3,
    "documents": [
      { "id": "doc_001", "name": "File1.pdf", "status": "UPLOADED" },
      { "id": "doc_002", "name": "File2.docx", "status": "UPLOADED" },
      { "id": "doc_003", "name": "File3.xlsx", "status": "UPLOADED" }
    ]
  }
}

Import from URL

POST /api/documents/upload-url

{
  "url": "https://example.com/docs/report-2025.pdf",
  "topicId": "topic_123",
  "description": "Annual report downloaded from the portal"
}

Size limits

Format	Maximum size
PDF	50 MB
DOCX, XLSX, PPTX	25 MB
TXT, CSV, MD	10 MB
HTML	5 MB

Max simultaneous uploads: 10 files per request. Rate limit: 10 uploads per minute.

List and search

GET /api/documents

Query parameters:

Parameter	Type	Default	Description
page	number	1	Current page
limit	number	20	Results per page (max 100)
search	string	-	Search in name and description
status	string	-	Filter by status: UPLOADED, PROCESSING, VECTORIZED, ERROR
topicId	string	-	Filter by category
mimeType	string	-	Filter by file type
sort	string	createdAt	Sort field: name, createdAt, updatedAt
order	string	desc	Direction: asc or desc

Example:

curl -X GET "https://api.queria.pro/api/documents?status=VECTORIZED&topicId=topic_123&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "doc_8f3a2b1c",
        "name": "supply_contract.pdf",
        "originalName": "supply_contract.pdf",
        "mimeType": "application/pdf",
        "size": 2458624,
        "status": "VECTORIZED",
        "chunkCount": 47,
        "topicId": "topic_123",
        "topicName": "Contracts",
        "createdAt": "2026-03-04T10:30:00Z",
        "updatedAt": "2026-03-04T10:31:15Z"
      }
    ],
    "pagination": { "page": 1, "limit": 10, "total": 156, "totalPages": 16 }
  }
}

Document details

Document information

GET /api/documents/:id

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "name": "supply_contract.pdf",
    "originalName": "supply_contract.pdf",
    "mimeType": "application/pdf",
    "size": 2458624,
    "status": "VECTORIZED",
    "topicId": "topic_123",
    "topic": {
      "id": "topic_123",
      "name": "Contracts",
      "color": "#3B82F6"
    },
    "description": "Service supply contract",
    "chunkCount": 47,
    "pageCount": 12,
    "processingInfo": {
      "ocrUsed": false,
      "language": "en",
      "processingTime": 15234
    },
    "createdAt": "2026-03-04T10:30:00Z",
    "updatedAt": "2026-03-04T10:31:15Z"
  }
}

Document chunks

GET /api/documents/:id/chunks

Returns the indexed text fragments with their metadata.

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "chk_001",
        "content": "Art. 1 - Subject of the contract. This agreement...",
        "chunkType": "ARTICLE",
        "chunkIndex": 0,
        "page": 1,
        "metadata": {
          "charCount": 680,
          "tokenCount": 180
        }
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 47, "totalPages": 3 }
  }
}

Processing status

GET /api/documents/:id/status

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "status": "PROCESSING",
    "currentStep": "EMBEDDING",
    "progress": 72,
    "steps": [
      { "name": "PARSING", "status": "completed", "duration": 1200 },
      { "name": "CHUNKING", "status": "completed", "duration": 800, "chunksCreated": 47 },
      { "name": "EMBEDDING", "status": "in_progress", "progress": 72 },
      { "name": "STORAGE", "status": "pending" }
    ]
  }
}

Document states

A document goes through the following states during processing:

UPLOADED --> PROCESSING --> VECTORIZED
                |
                +--> ERROR

State	Description
UPLOADED	File received, waiting for processing
PROCESSING	Active pipeline (parsing, chunking, embedding, storage)
VECTORIZED	Processing complete, document available for search
ERROR	Error during processing

Pipeline phases: PARSING -> CHUNKING -> EMBEDDING -> STORAGE.

Management

Update metadata

PUT /api/documents/:id

{
  "topicId": "topic_789",
  "description": "Updated document description",
  "confidentiality": "confidential"
}

Delete document

DELETE /api/documents/:id

Removes the document, all associated chunks and vectors from the vector database.

Bulk delete

DELETE /api/documents

{
  "documentIds": ["doc_8f3a2b1c", "doc_4d5e6f7g", "doc_1a2b3c4d"]
}

Reprocess document

POST /api/documents/:id/reprocess

Restarts the processing pipeline. Useful after updates to chunking or embedding configuration.

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "status": "PROCESSING",
    "message": "Reprocessing started"
  }
}

Download and preview

Original download

GET /api/documents/:id/download

Returns the original file with appropriate Content-Disposition headers.

Preview

GET /api/documents/:id/preview?page=1

{
  "success": true,
  "data": {
    "totalPages": 12,
    "currentPage": 1,
    "content": "Extracted page text...",
    "previewUrl": "/api/documents/doc_8f3a2b1c/preview-image?page=1"
  }
}

Document generation

Queria includes a template-based document generation engine.

Template list

GET /api/doc-engine/templates

Template schema

GET /api/doc-engine/templates/:id/schema

Returns the schema of the fields required for rendering.

Document rendering

POST /api/doc-engine/render

{
  "templateId": "tpl_report_standard",
  "data": {
    "title": "Q1 2026 Quarterly Report",
    "author": "Mario Rossi",
    "sections": [
      { "title": "Summary", "content": "..." },
      { "title": "Analysis", "content": "..." }
    ]
  },
  "format": "docx"
}

Returns the generated DOCX file as a direct download.

Common errors

Code	Error	Description
400	INVALID_FILE_TYPE	Unsupported file format
413	FILE_TOO_LARGE	File exceeds maximum size
422	PROCESSING_ERROR	Error during document processing

Webhook (Coming Soon)

Document events for asynchronous notifications:

Event	Description
document.uploaded	Document uploaded
document.vectorized	Processing completed
document.error	Processing error