Skip to main content
UnderstifyUnderstify
REST API — v1

API Reference

Programmatic access to document upload, analysis, Q&A, decision runs, and webhooks. 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.

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
}

Webhooks

Register a webhook endpoint from API & Webhooks settings to receive real-time event payloads. All payloads are signed with an HMAC-SHA256 signature in the X-Understify-Signature header.

document.analyzedFired when a document has been fully analyzed.
decision_run.completedFired when a decision run finishes successfully.
decision_run.failedFired when a decision run encounters an error.
decision_item.approvedFired when a decision item is approved.
decision_item.rejectedFired when a decision item is rejected.
decision_item.escalatedFired when a decision item is escalated.

Error Format

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

{
"error": {
"code": "SCOPE_REQUIRED",
"message": "This action requires the documents:write scope.",
"request_id": "req_abc123"
}
}