Integration guide
Input methods, permissions, processing, and error handling.
Authentication
Authenticate with a Bearer key. Scopes:
| Scope | Use |
|---|---|
document:read | Retrieve documents, results, exports, and verification results. |
document:write | Upload, merge, batch-process, or edit documents. |
document:delete | Delete documents. |
webhook:manage | Register and manage webhook endpoints. |
Input methods and limits
POST /documents accepts one of:
| Input | Request |
|---|---|
| Local file | Multipart file plus document_type. |
| Download URL | JSON file_url plus document_type. The URL must be reachable by Kita (e.g. an unexpired presigned URL). |
| Base64 | JSON file_base64, filename, and document_type. |
Limit: 100 MB per file. Formats: PDF, PNG, JPG/JPEG, TIFF/TIF, BMP, TXT,
CSV, XLSX, XLS. Send password for encrypted PDFs. Use original files where possible.
Processing and retries
Poll by document_id until completed or failed, with backoff and a timeout.
A client timeout does not cancel processing.
| Endpoint | Status field | Completed result |
|---|---|---|
/documents/jobs/{document_id} | status | result (processing output). |
/documents/{document_id} | document.status | document.result (normalized result). |
If an upload response is lost, check the document list before retrying. Reuploads
can create new records even when a completed extraction is reused (see
document.processing).
Webhooks
Pass webhook_url with an upload, or register a signed webhook.
Deduplicate repeated notifications, fetch results with your API key, and keep
polling as a fallback.
Batch or merge
- Batch: process up to 100 separate documents. Each has its own result. Requires a paid plan.
- Merge: combine 2–50 PDF/image inputs into one document and one result.
See API reference for requests and responses.
Errors
Errors generally return error and message. request_id and details are
not always present.
| Status | What to do |
|---|---|
400 | Correct the input, document type, or identifier. |
401 | Check the API key and Bearer header. |
402 / 403 | Check credits, plan, scopes, and enabled document types. |
404 | Check the ID and organization. |
413 / 415 | Reduce the file size or use a supported format. |
429 | Back off; honor Retry-After when present. |
500 / 502 / 503 | Retry reads with backoff. Check for a created document before retrying uploads. |
A job can fail after 202; check status even when polling returns 200.
For support, send the document ID and any request ID.