Skip to main content

Documents REST API

The Documents REST API provides endpoints for file upload, classification, and document management.

Base URL​

/api/eai/v3/documents

Upload Document​

Upload a file with multipart form data.

POST /api/eai/v3/documents
Content-Type: multipart/form-data

Form Fields​

FieldTypeRequiredDescription
fileFileYesFile to upload
typestringNoDocument type/category
tagsstring[]NoTags (comma-separated)
autoClassifybooleanNoAuto-classify on upload
autoIndexbooleanNoAuto-index for RAG
metadatastringNoJSON metadata string

Example Request (JavaScript)​

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('type', 'contract');
formData.append('tags', 'legal,pending-review');
formData.append('autoClassify', 'true');
formData.append('autoIndex', 'true');

const response = await fetch('/api/eai/v3/documents', {
  method: 'POST',
  body: formData
});

const document = await response.json();

Example Request (curl)​

curl -X POST "/api/eai/v3/documents" \
  -F "file=@contract.pdf" \
  -F "type=contract" \
  -F "tags=legal,pending-review" \
  -F "autoClassify=true"

Response​

{
  "id": "doc_abc123",
  "filename": "contract.pdf",
  "type": "contract",
  "contentType": "application/pdf",
  "size": 245760,
  "url": "https://storage.example.com/docs/contract.pdf",
  "status": "uploaded",
  "tags": ["legal", "pending-review"],
  "createdAt": "2026-03-11T14:00:00Z"
}

List Documents​

GET /api/eai/v3/documents

Query Parameters​

ParameterTypeDescription
typestringFilter by type
tagsstringFilter by tags (comma-separated)
statusstringFilter by status
indexedbooleanFilter by indexing status
limitnumberMax results (default: 50)
offsetnumberPagination offset

Example Request​

const response = await fetch('/api/eai/v3/documents?' + new URLSearchParams({
  type: 'contract',
  status: 'ready',
  indexed: 'true',
  limit: '20'
}));

const { data: documents } = await response.json();

Response​

{
  "data": [
    {
      "id": "doc_abc123",
      "filename": "contract.pdf",
      "type": "contract",
      "size": 245760,
      "url": "https://storage.example.com/docs/contract.pdf",
      "status": "ready",
      "indexed": true,
      "classification": {
        "category": "legal-contract",
        "confidence": 0.95
      },
      "createdAt": "2026-03-11T14:00:00Z"
    }
  ],
  "total": 15,
  "hasMore": false
}

Get Document​

GET /api/eai/v3/documents/:id

Response​

{
  "id": "doc_abc123",
  "filename": "contract.pdf",
  "type": "contract",
  "contentType": "application/pdf",
  "size": 245760,
  "url": "https://storage.example.com/docs/contract.pdf",
  "status": "ready",
  "classification": {
    "category": "legal-contract",
    "confidence": 0.95,
    "extractedData": {
      "contractType": "Service Agreement",
      "parties": ["Acme Corp", "XYZ Inc"],
      "effectiveDate": "2026-01-01"
    }
  },
  "indexed": true,
  "tags": ["legal", "approved"],
  "createdAt": "2026-03-11T14:00:00Z"
}

Classify Document​

POST /api/eai/v3/documents/:id/classify

Response​

{
  "category": "legal-contract",
  "subcategory": "service-agreement",
  "confidence": 0.95,
  "extractedData": {
    "contractType": "Service Agreement",
    "parties": ["Acme Corp", "XYZ Inc"]
  }
}

Index Document​

POST /api/eai/v3/documents/:id/index

Request Body​

{
  "chunkSize": 1500,
  "chunkOverlap": 300
}

Response​

{
  "documentId": "doc_abc123",
  "chunks": 45,
  "status": "indexed"
}

Search Documents​

POST /api/eai/v3/documents/search

Request Body​

{
  "query": "termination clause",
  "limit": 10,
  "minScore": 0.7,
  "type": "contract"
}

Response​

{
  "results": [
    {
      "documentId": "doc_abc123",
      "filename": "contract.pdf",
      "chunk": "Either party may terminate this agreement...",
      "score": 0.92,
      "metadata": {
        "pageNumber": 5
      }
    }
  ]
}

Delete Document​

DELETE /api/eai/v3/documents/:id

Response​

204 No Content

Supported File Types​

  • Documents: PDF, DOC, DOCX, TXT, RTF
  • Spreadsheets: XLS, XLSX, CSV
  • Images: JPG, PNG, GIF, WEBP
  • Maximum size: 100 MB

Error Responses​

413 Payload Too Large​

{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File exceeds 100 MB limit"
  }
}

415 Unsupported Media Type​

{
  "error": {
    "code": "UNSUPPORTED_FILE_TYPE",
    "message": "File type not supported"
  }
}

Next Steps​