Developers

ADRE API documentation

A public REST API for document classification, structured data extraction and batch processing with a completion webhook.

Authentication

Every request to /api/v1/* must include an x-api-key header with your key. Keys are issued individually - use the demo request form to get access.

Document recognition

POST /api/v1/recognize accepts a single document (a base64 image or a PDF) and returns structured fields. The docType parameter is optional - without it the document type is detected automatically; if it is provided and matches one of the supported types, recognition is faster and more accurate.

Request

POST /api/v1/recognize
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "image": "<base64>",
  "mimeType": "image/jpeg",
  "docType": "Справка"
}

Response

{
  "documentType": "Справка",
  "text": "...",
  "fields": [
    { "label": "ФИО", "value": "Асанов Азамат", "confidence": 97 },
    { "label": "Дата выдачи", "value": "01.03.2026", "confidence": 92 }
  ],
  "items": [],
  "confidence": 94
}

confidence is the model’s own self-assessment (0–100) for the whole document and separately for each field: not a guarantee of accuracy, but a useful signal for what to review manually. Supported file types: image/png, image/jpeg, image/webp, application/pdf, up to ~4 MB per file.

Batch processing

If you are processing a group of documents and want a notification once it is done, open a batch, pass the returned batchId in the "batchId" field of every /api/v1/recognize call in that group, then close the batch.

Open a batch

POST /api/v1/batch
x-api-key: YOUR_API_KEY

{}

→ { "batchId": "batch_abc123", "createdAt": "2026-09-08T10:00:00Z" }

Close a batch

POST /api/v1/batch
x-api-key: YOUR_API_KEY

{ "batchId": "batch_abc123", "finish": true }

→ {
  "batchId": "batch_abc123",
  "documentCount": 24,
  "errorCount": 0,
  "docTypeCounts": { "Справка": 24 },
  "webhookAttempted": true,
  "webhookDelivered": true
}

Batch completion webhook

If a webhook URL is configured for your key, closing a batch automatically sends it a POST request with a summary. On delivery failure, up to 3 retries are attempted; closing an already-closed batch again does not resend the webhook.

POST <ваш webhookUrl>
X-Tamga-Event: batch.completed
X-Tamga-Signature: sha256=<HMAC-SHA256 тела запроса>

{
  "event": "batch.completed",
  "batchId": "batch_abc123",
  "documentCount": 24,
  "errorCount": 0,
  "docTypeCounts": { "Справка": 24 },
  "createdAt": "2026-09-08T10:00:00Z",
  "closedAt": "2026-09-08T10:04:12Z",
  "deliveredAt": "2026-09-08T10:04:12Z"
}

The X-Tamga-Signature header is present only if a signing secret is configured for your key - verify it against the HMAC-SHA256 of the raw request body on your side to confirm the webhook came from ADRE.

Error codes

An error response always contains { "error": "message" } together with the matching HTTP status.

401Invalid or missing x-api-key

400Malformed request body - for example, mimeType is missing or unsupported

413File exceeds the size limit (~4 MB)

404No batch found with this batchId

403This batch was created with a different x-api-key

500Internal server error - retry later

Limits

Maximum file size is about 4 MB per document/page. Throughput is discussed individually based on your plan - contact us if you are planning a high volume.

Supported document types

Over 20 standard document types (identity documents, civil records, diplomas, contracts, banking and accounting documents and more - see the "Supported documents" section on the home page), plus custom types your company can define through the admin panel.