API overview

The Collate Prior Auth API is an HTTP JSON API. Hand-authored guides explain the workflows; the API Reference lists exact endpoint schemas from OpenAPI.

The raw HTTP reference is the source of truth for endpoint shapes and error envelopes. Python and TypeScript SDKs are available in beta for eligible organizations.

Base URLs

Sandbox and production use separate API keys.

Use separate keys for sandbox and production, and keep all API keys server-side.

Authentication

Authenticate every /v1/* request with a bearer token:

1
Authorization: Bearer <API_KEY>

Only GET /health is public.

Idempotency

Send Idempotency-Key when creating an authorization:

1
POST /v1/prior-authorizations
2
Idempotency-Key: create-auth-7b984f1d

Create is the only public endpoint that requires a client idempotency key. Reusing the same key with the same body returns the original result. Reusing it with a different body returns 409 idempotency_key_reused.

Existing-resource mutations use If-Match and server-side retry protection. Do not invent public idempotency headers for those commands.

Optimistic concurrency

Mutable authorization and manual-handoff operations require the current resource version in If-Match.

1
If-Match: "17"

Stale versions return 409 version_conflict. Re-read the resource and retry only if the new state still needs the same action.

Pagination

List endpoints use cursor pagination.

Responses include pagination.nextCursor when another page is available.

Files

The public upload flow is POST /v1/files, PUT <upload.url>, POST /v1/files/{fileId}/complete, then POST /v1/prior-authorizations/{authorizationId}/attachments.

Only authorization_attachment files can be linked as public authorization attachments.

Error envelope

Every typed error uses the same envelope:

1
{
2
  "error": {
3
    "code": "version_conflict",
4
    "message": "Authorization version does not match If-Match.",
5
    "retryable": false,
6
    "details": { "expectedVersion": 2, "actualVersion": 3 },
7
    "issues": []
8
  },
9
  "requestId": "req_123"
10
}

Match error.code to recover. See Errors and troubleshooting.

Public resources

Build against these public resources:

Internal executions, portal claims, replay segments, evidence rows, and raw runtime URLs are not public API resources.