REST API Reference

DocIntel exposes a FastAPI REST API on port 8200. Interactive docs available at http://localhost:8200/docs.

Authentication

All endpoints require a Bearer token:

Authorization: Bearer <SERVER__API_KEY>

Set SERVER__API_KEY in your .env file.

---

Process a document

POST /process

Upload a file for extraction.

POST /process
Content-Type: multipart/form-data
Authorization: Bearer <token>

Form fields:

Field	Type	Required	Description
file	file	✅	Document to process
profile	string	❌	aec | contract | financial | scientific | general (auto-detected if omitted)
language	string	❌	ISO 639-1 language code (e.g. de, fr, ja). Auto-detected if omitted. Activates language-specific extraction prompts for 75+ supported languages.
emit	boolean	❌	Emit to Purple8 Graph on completion (default: true)
preview	boolean	❌	Emit to /ingest/preview instead of /ingest/commit

Response:

{
  "job_id": "abc-123",
  "status": "queued",
  "created_at": "2026-04-01T12:00:00Z"
}

---

POST /process/url

Submit a URL for extraction. SSRF-guarded — RFC 1918, loopback, link-local, and cloud metadata endpoints are blocked.

POST /process/url
Content-Type: application/json
Authorization: Bearer <token>

{
  "url": "https://example.com/report.pdf",
  "profile": "scientific",
  "emit": true
}

---

Jobs

GET /jobs/{job_id}

Poll a job for status and results.

{
  "job_id": "abc-123",
  "status": "completed",
  "profile": "contract",
  "content_hash": "sha256:a1b2c3d4e5f6...",
  "entities": [
    {
      "type": "Party",
      "name": "Acme Corporation",
      "confidence": 0.74,
      "source_chunk_ids": ["chunk-0", "chunk-2"]
    }
  ],
  "relationships": [
    {
      "source": "Acme Corporation",
      "target": "GlobalTech Ltd",
      "type": "SIGNED_BY",
      "confidence": 0.67
    }
  ],
  "metadata": {
    "format": "pdf",
    "pages": 12,
    "language": "en",
    "processing_ms": 4230,
    "incremental_skip": false,
    "tables_injected": 3
  }
}

Status values: queued · running · completed · failed

Incremental processing

If the same document (by SHA-256 content hash) has already been processed, the job is completed instantly with "incremental_skip": true and the cached extraction result is returned. No LLM calls are made.

---

GET /jobs/{job_id}/stream

Stream partial results via Server-Sent Events as each chunk completes.

curl -N http://localhost:8200/jobs/abc-123/stream \
  -H "Authorization: Bearer $API_KEY"

Event format:

event: entity
data: {"type":"Party","name":"Acme Corporation","confidence":0.94}

event: relationship
data: {"source":"Acme Corporation","target":"GlobalTech Ltd","type":"SIGNED_BY"}

event: done
data: {"job_id":"abc-123","status":"completed"}

---

GET /jobs

List recent jobs.

Query param	Default	Description
limit	20	Max jobs to return
status	all	Filter by status
profile	all	Filter by profile

---

Connectors

POST /connectors/sync/sharepoint

Trigger a SharePoint library sync.

{
  "site_url": "https://myorg.sharepoint.com/sites/mysite",
  "library": "Documents",
  "profile": "general",
  "recursive": true
}

POST /connectors/sync/confluence

{
  "base_url": "https://myorg.atlassian.net/wiki",
  "space_key": "ENG",
  "profile": "scientific"
}

POST /connectors/sync/s3

{
  "bucket": "my-bucket",
  "prefix": "reports/2026/",
  "glob": "*.pdf",
  "profile": "financial"
}

POST /connectors/webhook

Generic webhook — POST file bytes or a URL reference:

{
  "url": "https://internal-dms.example.com/doc/12345.docx",
  "profile": "contract",
  "metadata": {
    "source": "my-dms",
    "doc_id": "12345"
  }
}

---

Health & observability

Endpoint	Description
GET /health	Liveness probe — returns {"status": "ok"}
GET /ready	Readiness probe — checks LLM + Graph connectivity
GET /license	License status — tier, quotas, features, expiry
GET /formats	List all supported document formats
GET /metrics	Prometheus metrics
GET /docs	Swagger UI (interactive API explorer)
GET /redoc	ReDoc API documentation
GET /openapi.json	OpenAPI schema

---

GET /license

Returns the current license status, including tier, features, quotas, and expiry information.

{
  "valid": true,
  "tier": "pro",
  "license_id": "abc-123",
  "org_name": "Acme Corp",
  "features": ["table_extraction", "multi_language", "confidence_calibration", "incremental_processing"],
  "quotas": {
    "documents_per_month": 5000,
    "workers": 8,
    "connectors": ["s3", "webhook", "sharepoint", "confluence"],
    "ocr_engines": ["tesseract", "azure_doc_intel", "google_vision", "textract"],
    "llm_providers": ["openai", "azure", "anthropic", "gemini", "ollama"]
  },
  "expires_at": "2027-04-07T00:00:00Z",
  "days_remaining": 365
}

If no license key is set, the server runs in unlicensed Beta mode with limited quotas (500 docs/month).

---

GET /ready

Readiness probe that verifies LLM and Graph connectivity.

{
  "status": "ready",
  "checks": {
    "llm": "ok",
    "graph": "ok"
  }
}

---

GET /formats

List all supported document formats with parser information.

{
  "formats": [
    {"format": "pdf", "extensions": [".pdf"], "parser": "PdfParser"},
    {"format": "docx", "extensions": [".docx", ".doc", ".odt"], "parser": "DocxParser"},
    ...
  ]
}

---

DELETE /jobs/{job_id}

Cancel or remove a job.

curl -X DELETE http://localhost:8200/jobs/abc-123 \
  -H "Authorization: Bearer $API_KEY"

{
  "job_id": "abc-123",
  "status": "cancelled"
}