AI Document Conversion API Reference

Complete reference for all endpoints, authentication, request formats, and error handling.

Authentication

All requests except health checks require a Bearer token in the Authorization header. Tokens are compared using constant-time comparison to prevent timing attacks.

Header

Authorization: Bearer YOUR_API_KEY

Rate limiting: Default limit is 10 requests per minute per API key. Enterprise agreements include custom rate limits. Exceeded limits return HTTP 429.

How this API fits into the platform

Platform-consumed API — This conversion service is consumed by the DocAccessible platform, not called directly by end users or clients.
Human review gate — Every conversion passes through admin review before delivery. The accessibility score drives deliver/retry decisions.
Client acceptance — After admin delivery, clients formally accept, request revisions, or provide feedback through a separate downstream workflow.
Full audit trail — Typed domain events track every stage: conversion triggered, completed, failed, delivered, accepted.

POST

/convert

Convert a PDF document to accessible HTML. Accepts multipart form data with the file and optional metadata fields. Large documents (>20 pages) are automatically chunked and stitched.

Request fields

Field	Type	Required	Description
file	File	Required	The PDF file to convert. Maximum size defined by server configuration (default 50 MB).
source_format	string	Optional	Source format hint. Currently only "pdf" is supported. Defaults to "pdf".
page_count	number	Optional	Total page count if known. Used for chunking optimization on large documents.
request_id	string	Optional	Your external request identifier for correlation. Returned in response metadata.
job_id	string	Optional	Your external job identifier for correlation. Returned in response metadata.

Response schema

200 OK

{
  "html": "string — Full accessible HTML document including DOCTYPE, head, and body",
  "metadata": {
    "model": "string — AI model used (e.g. claude-sonnet-4-20250514)",
    "processing_time_ms": "number — Total wall-clock processing time",
    "pages_processed": "number — Pages extracted and converted",
    "tokens_used": {
      "input": "number — Input tokens consumed",
      "output": "number — Output tokens generated"
    },
    "extraction": {
      "images_found": "number — Images detected in PDF",
      "tables_found": "number — Tables detected in PDF",
      "has_form_fields": "boolean — Whether form fields were found",
      "ocr_recommended": "boolean — True if document appears to be image-only"
    },
    "document": {
      "title": "string | null — Document title from PDF metadata",
      "author": "string | null — Author from PDF metadata",
      "language": "string | null — Detected document language"
    },
    "accessibility_score": "number — 0-100 score from 12-rule validation"
  }
}

GET

/

Root service info endpoint. Returns the service name, version, and status. Does not require authentication. Used by Coolify, load balancers, and deployment probes to verify the service is running.

200 OK

{
  "service": "@docaccessible/conversion-service",
  "version": "string — Service version from package.json",
  "status": "running",
  "docs": "/health"
}

GET

/ready

Readiness probe. Verifies that Poppler is available and the Anthropic API key is configured. Does not require authentication. Returns 200 when ready, 503 when not.

200 OK / 503 Service Unavailable

{
  "ready": "boolean — true if all dependencies are available",
  "checks": {
    "poppler": "boolean — pdfinfo binary available",
    "anthropicKeyConfigured": "boolean — ANTHROPIC_API_KEY is set"
  }
}

GET

/health

Shallow health check. Returns service status and version. Does not require authentication. Use this as your load balancer or uptime monitor target.

200 OK

{
  "status": "ok | degraded",
  "version": "string — Service version from package.json",
  "uptime": "number — Process uptime in seconds",
  "checks": {
    "poppler": "boolean — pdfinfo binary available",
    "anthropic": "boolean — API key configured (shallow) or connectivity verified (deep)"
  }
}

GET

/health/deep

Deep health check. Verifies Poppler availability and tests Anthropic API connectivity with a minimal request. Does not require authentication. Use sparingly — this makes an external API call.

Returns the same schema as /health but with verified checks.anthropic status.

Error codes

All errors follow a consistent envelope format. The code field is machine-readable for programmatic handling.

Error envelope

{
  "error": {
    "message": "string — Human-readable error description",
    "code": "string — Machine-readable error code",
    "details": "string | undefined — Additional context when available"
  }
}

Code	HTTP	Description
VALIDATION_ERROR	422	Request validation failed — missing file, unsupported format, or invalid parameters.
RATE_LIMIT_EXCEEDED	429	Too many requests. Default limit is 10 requests per minute per API key.
UNAUTHORIZED	401	Missing or malformed Authorization header.
FORBIDDEN	403	Invalid API key. Constant-time comparison prevents timing attacks.
SERVICE_UNAVAILABLE	503	Upstream AI service temporarily unavailable. Retry with exponential backoff.
INTERNAL_ERROR	500	Unexpected server error. Includes a request trace ID for support.

Get enterprise API access

Custom rate limits, SLA guarantees, and dedicated support for your production workloads.

Contact Sales Overview