Skip to main content
Understify
REST API — v1

API Reference

Programmatic access to document upload, analysis, Q&A and decision runs. All endpoints return JSON over HTTPS and authenticate via API keys.

Generate an API keyRequest full OpenAPI spec
Quick start
# Upload a document
curl -X POST https://understify.com/api/v1/documents/upload \
  -H "Authorization: Bearer usk_live_xxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@contract.pdf"

# List decision runs
curl https://understify.com/api/v1/decision-runs \
  -H "Authorization: Bearer usk_live_xxxx"

Authentication

All API requests must include your API key in the Authorization header using Bearer token format.

Authorization: Bearer usk_live_xxxxxxxxxxxxxxxxxxxx

Scopes

API keys support fine-grained scopes: documents:read, documents:write, decisions:read, decisions:write, or * for full access.

Rate Limits

Limits vary by plan. Exceeded requests return 429 Too Many Requests with Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining headers.

Request Format

Every request that sends a body must declare its type: Content-Type: application/json, or multipart/form-data for document upload. A body with no Content-Type, or with another type (for example application/x-www-form-urlencoded, which is what curl -d sends by default), is refused before it reaches the endpoint with HTTP 415 and this body:

{
"error": "Unsupported content type",
"code": "UNSUPPORTED_MEDIA_TYPE"
}

This response comes from the gateway, so it does not use the error format below. With curl, add -H "Content-Type: application/json" whenever you pass -d. Requests without a body (GET, or a DELETE with no body) are not affected.

Idempotency

Mutating endpoints (e.g. document upload) support idempotent retries. Pass a unique Idempotency-Key header (UUID v4 recommended). Duplicate requests with the same key within 24 hours return the original response without re-processing.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Endpoints

GET/api/v1/documents
documents:read

List documents with cursor-based pagination.

POST/api/v1/documents/upload
documents:write

Upload a document. Supports Idempotency-Key header.

GET/api/v1/documents/:id
documents:read

Retrieve a single document by ID.

POST/api/v1/documents/:id/qa
documents:read

Ask a question about a document. Returns a contextual answer.

GET/api/v1/decision-runs
decisions:read

List decision runs with filters and cursor pagination.

GET/api/v1/decision-runs/:id
decisions:read

Retrieve a single decision run with all associated items.

Pagination

List endpoints use cursor-based pagination. Pass ?cursor=<next_cursor> and ?limit=20 (max 100) to page through results. Responses include a next_cursor field when more results exist.

{
"data": [...],
"next_cursor": "doc_abc123",
"has_more": true
}

Error Format

All errors return a consistent JSON body with a machine-readable code field.

{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}