Documents API

Document management endpoints.

List Documents

Get all documents for the current user.

GET /api/v1/documents
Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Description
limit	int	Items per page (default: 20)
cursor	string	Pagination cursor
status	string	Filter by status
search	string	Search by name

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "doc-uuid",
      "name": "Contract 2026",
      "original_name": "contract.pdf",
      "type": "pdf",
      "mime_type": "application/pdf",
      "size": 1024000,
      "page_count": 5,
      "status": "ready",
      "encrypted": true,
      "created_at": "2026-01-24T10:00:00Z",
      "updated_at": "2026-01-24T10:00:00Z"
    }
  ],
  "meta": {
    "limit": 20,
    "has_more": true,
    "next_cursor": "abc123"
  }
}

Upload Document

Upload a new document.

POST /api/v1/documents
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

Request

Field	Type	Required	Description
file	file	Yes	Document file (PDF, DOCX, XLSX)
name	string	No	Display name
tags	array	No	Document tags

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "doc-uuid",
    "name": "Contract 2026",
    "original_name": "contract.pdf",
    "type": "pdf",
    "mime_type": "application/pdf",
    "size": 1024000,
    "page_count": 5,
    "status": "processing",
    "encrypted": true,
    "created_at": "2026-01-24T10:00:00Z"
  }
}

Get Document

Get document details.

GET /api/v1/documents/:id
Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "doc-uuid",
    "name": "Contract 2026",
    "original_name": "contract.pdf",
    "type": "pdf",
    "mime_type": "application/pdf",
    "size": 1024000,
    "page_count": 5,
    "status": "ready",
    "encrypted": true,
    "hash": "sha256:abc123...",
    "tags": ["contract", "2026"],
    "metadata": {
      "author": "John Doe"
    },
    "created_at": "2026-01-24T10:00:00Z",
    "updated_at": "2026-01-24T10:00:00Z"
  }
}

Update Document

Update document metadata.

PUT /api/v1/documents/:id
Authorization: Bearer <access_token>

Request

{
  "name": "Updated Contract Name",
  "tags": ["contract", "updated"]
}

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "doc-uuid",
    "name": "Updated Contract Name",
    "tags": ["contract", "updated"],
    "updated_at": "2026-01-24T11:00:00Z"
  }
}

Delete Document

Delete a document.

DELETE /api/v1/documents/:id
Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "message": "Document deleted successfully"
  }
}

Download Document

Download the original document file.

GET /api/v1/documents/:id/download
Authorization: Bearer <access_token>

Response

Returns the file binary with appropriate headers:

Content-Type: application/pdf
Content-Disposition: attachment; filename="contract.pdf"

Document Status

Status	Description
processing	Document is being processed
ready	Document is ready for use
error	Processing failed

Supported File Types

Type	Extensions	Max Size
PDF	.pdf	25 MB
Word	.docx	25 MB
Excel	.xlsx	25 MB

Error Codes

Code	Description
DOCUMENT_NOT_FOUND	Document does not exist
DOCUMENT_PROCESSING	Document still processing
FILE_TOO_LARGE	File exceeds size limit
UNSUPPORTED_TYPE	File type not supported