Integration guide
Input methods, permissions, processing, and error handling.
Authentication
Use your Bearer key. Scopes control access:
| 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 these inputs:
| Input | Request |
|---|---|
| Local file | Multipart file plus document_type. |
| Download URL | JSON file_url plus document_type. Use a URL reachable by Kita, such as 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 using document_id until completed or failed. Use backoff and a timeout;
a network 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. Reuse details
appear in document.processing.
Webhooks
Pass webhook_url with an upload, or register a signed webhook.
Handle repeated notifications once, retrieve 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
Route errors generally return error and message. Some include request_id
and details; do not require those fields on every response.
| 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 its status even when polling returns 200.
For support, include the document ID and any returned request ID.