API Conventions

Conventions for authentication, idempotency, webhooks, errors, pagination, and asynchronous operations.

Scope

This page defines the conventions used across the Numora Public API developer preview.

Base Path and Versioning

Public routes live under /v1.
Internal app routes remain separate.
Schema versions are explicit in resource fields, for example invoice_v2.

Authentication

The public API uses API keys rather than browser session cookies.

Authentication model:

Authorization: Bearer <api_key>
One-time secret reveal at creation time
Server-side hash storage
Key scopes
Key rotation and revocation

Idempotency

The current preview uses resource-specific identifiers as the primary idempotency model.

Current guidance:

use external_id for document creation reconciliation
use execution_id for delivery callback reconciliation

Do not assume that a generic Idempotency-Key header is the primary retry contract across all current /v1 mutating routes.

Webhooks

Webhook delivery is a first-class integration mechanism.

Event types:

document.processing
document.review_required
document.reviewed
push.succeeded
push.failed
run.failed

Delivery model:

HMAC signature with timestamp
Raw request body verification
Retry with backoff
Delivery logs per endpoint

Error Model

Error responses use a stable error body:

{
  "error": {
    "code": "invalid_schema",
    "message": "schema must be one of invoice_v2, receipt_v1, contract_v1",
    "request_id": "req_01jpwqkshg6x8j9k9j29m8n0n4"
  }
}

Error classes:

unauthorized
forbidden
invalid_payload
invalid_schema
not_found
conflict
rate_limited
internal_error

Pagination

List routes use cursor pagination for long-lived public endpoints.

Suggested response shape:

{
  "data": [],
  "next_cursor": "cur_01jpwqv8k0fbbbx7k2y7w1v7r7"
}

Operational Headers

Operational headers:

x-request-id
retry-after on 429
x-rate-limit-limit
x-rate-limit-remaining
x-rate-limit-reset

If an operation can take multiple seconds, fan out to background processing, or call third-party systems, the API returns 202 Accepted and exposes a retrievable resource instead of holding a long synchronous request open.