API Reference

Base URL#

http://localhost:8008/api/v1/docs

Endpoints#

POST /api/v1/docs/upload#

Upload a document file for processing.

Request: multipart/form-data

curl -X POST http://localhost:8008/api/v1/docs/upload -F "file=@emirates_id.pdf"

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "filename": "emirates_id.pdf",
  "file_type": "pdf",
  "status": "pending",
  "message": "Document uploaded successfully"
}

POST /api/v1/docs/ocr#

Run OCR text extraction on an uploaded document. Engine selection is automatic based on file type.

curl -X POST "http://localhost:8008/api/v1/docs/ocr?document_id=DOC_ID"

Response:

{
  "text": "United Arab Emirates\nEmiratesID\n784-1990-1234567-1\nالهوية الإماراتية",
  "confidence": 0.92,
  "language": "mixed",
  "blocks": [
    {
      "text": "United Arab Emirates",
      "confidence": 0.98,
      "bbox": [[10, 20], [200, 20], [200, 50], [10, 50]]
    }
  ]
}

POST /api/v1/docs/classify#

Classify the document type using LLM analysis of the OCR text.

curl -X POST "http://localhost:8008/api/v1/docs/classify?document_id=DOC_ID"

Response:

{
  "document_type": "identity",
  "confidence": 0.95,
  "sub_type": "emirates_id",
  "keywords": ["Emirates ID", "الهوية", "784"]
}

POST /api/v1/docs/extract#

Extract structured fields, tables, and dates from a classified document.

curl -X POST "http://localhost:8008/api/v1/docs/extract?document_id=DOC_ID"

Response:

{
  "fields": [
    {"key": "full_name", "value": "Ahmed Al Maktoum", "confidence": 0.97, "field_type": "text"},
    {"key": "id_number", "value": "784-1990-1234567-1", "confidence": 0.99, "field_type": "text"},
    {"key": "expiry_date", "value": "2028-03-15", "confidence": 0.94, "field_type": "date"}
  ],
  "tables": [],
  "dates": ["2028-03-15"],
  "summary": "Emirates ID card for Ahmed Al Maktoum, expiring March 2028"
}

POST /api/v1/docs/validate#

Validate extracted fields for completeness and format correctness.

curl -X POST "http://localhost:8008/api/v1/docs/validate?document_id=DOC_ID"

Response:

{
  "is_valid": true,
  "completeness_score": 0.85,
  "issues": [
    {"field": "nationality", "issue": "Missing required field", "severity": "warning"}
  ]
}

GET /api/v1/docs/documents#

List all processed documents with pagination and search.

curl "http://localhost:8008/api/v1/docs/documents?page=1&page_size=20&search=emirates"

Response:

{
  "documents": [
    {
      "id": "a1b2c3d4...",
      "filename": "emirates_id.pdf",
      "file_type": "pdf",
      "status": "completed",
      "document_type": "identity",
      "confidence": 0.95,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20
}

GET /api/v1/docs/documents/{id}#

Get full details for a specific document including OCR text, classification, extracted fields, and validation results.

curl http://localhost:8008/api/v1/docs/documents/DOC_ID

Environment Variables#

MCP Server#

Docs AI exposes a Model Context Protocol server at /mcp, enabling integration with AI assistants and development tools that support the MCP specification.