Brellium API overview

The Brellium API is an HTTPS and JSON interface to Brellium's clinical documentation review, scoped to your organization. It covers the documents you send, the audits and coding evaluations Brellium produces from them, and the question sets audits are scored against. It also covers the users who sign in to Brellium and the email recipients who get audit emails. Use it to upload documents, pull audit results into your systems, keep them in sync, update audit flags and manage who gets audit emails.

Base URL

Every request goes to one host, and every resource is under /v2:

https://api.brellium.com

GET /v2/openapi.json returns the OpenAPI 3.1 document of the running API, and the API reference is built from it. The API is plain HTTPS and JSON, and the TypeScript and Python SDKs are optional (Clients and SDKs).

One organization per token

An access token is bound to the organization that owns its key, and a request made with it reaches only that organization's records.

Mint a token at POST /v2/oauth/token with the client id and secret of a key from the dashboard, and reuse it until it expires. A live key works on your organization's records. A sandbox key works on sample data, so use one to build and test without changing your organization's records. For keys, the token request and caching, see Authenticate with OAuth2 client credentials.

Resources

Resource	Path	What it is
Documents	`/v2/documents`	The documents you send for review. `POST /v2/documents` creates 1 to 100 documents as one batch and returns an upload URL for each. Brellium starts processing each document once you `PUT` its file to the upload URL. For the upload flow, see Upload documents.
Audits	`/v2/audits`	The result of scoring one or more documents against a question set: `status`, `score`, `flags`, one response per question, and the ids of the documents and people involved. `flags` is the only field you can change.
Coding evaluations	`/v2/coding_evaluations`	Read-only checks of the codes submitted for an encounter, each with an evaluation and management (E/M) result (`em_evaluation`) and an International Classification of Diseases (ICD) result (`icd_evaluation`). Each result is `null` until `status` is `complete`, or when there is no result to show.
Users	`/v2/users`	The people who can sign in to Brellium for your organization; creating one emails an invitation.
Email recipients	`/v2/email_recipients`	The people who receive audit emails; a recipient's `person_id` is what an audit shows in `people[].person_id`.
Question sets	`/v2/question_sets`	The questions an audit is scored against. Question sets are read-only, and each one includes its `questions`.

Every list uses cursor pagination. Every list also accepts include_total=true, and you can repeat its id field, or separate the ids with commas, for a batch get (?audit_id=<id>&audit_id=<id> or ?audit_id=<id>,<id>). For the pagination rules and each resource's filters, see Page through and filter lists.

An audit or coding evaluation carries only the ids of its related records (set_id, documents[], people[].person_id, audit_id); fetch each from its own endpoint. For every audit field, see Understand an audit.

Conventions

These rules apply across the API:

Field names are snake_case. Each resource has its own id field (audit_id, user_id, and person_id for an email recipient) and an object field naming its type ("object": "audit", "object": "email_recipient").
Timestamps are RFC 3339 in UTC with a trailing Z (2026-09-24T02:37:12.105Z). Filters such as created_after and updated_before take the same format.
Every list has the same envelope, { "object": "list", "data": [ ... ], "has_more": true }, with items newest first. There is no next_cursor; for the next page, pass the last item's id (its audit_id, for example) as starting_after. include_total=true adds total_count.
Every /v2 error response is one JSON envelope: { "error": { "type", "code", "message", "param"?, "details"?, "request_id" } }. Branch on type and code, which are stable; message and details can change. For every code, see Rate limits and errors.
Every response carries an x-request-id header, which equals error.request_id on an error.
A bare 403, 413, 414 or 431 is the exception to the two rules above: it has no JSON body and no x-request-id (Rate limits and errors).
Your organization can send a burst of 100 requests, then 5 per second, shared by every key; the sandbox has a separate budget with the same limits. For the rate limit headers and the retry rules, see Rate limits and errors.
Send Content-Type: application/json with every request body. On a /v2 endpoint, any other content type, or none, returns 400 INVALID_CONTENT_TYPE.

Freshness

Reads can take a few seconds to reflect a create, change or delete:

Lists can take a few seconds to include a new or changed record, or to drop a deleted one. To sync incrementally, make consecutive updated_after windows overlap; for the loop, see Keep audits in sync with updated_after.
For the same few seconds, a retrieve endpoint, such as GET /v2/audits/{audit_id}, can return 404 for a new record or the previous version of a changed one.
A create or update response is the current record, so use it instead of fetching the record again.

Where to start

Make your first request

Mint a token, make a read-only call, read your first audit.

Authenticate with OAuth2 client credentials

Create a key, mint a token with it, cache the token, and handle 401, 429 and 502.

Upload documents

Create documents, upload each file, and follow them through processing, expiry and zips.

Test with a sandbox key

Call the same API against sample data with a sandbox key, then reset the sandbox.

Retrieve an audit by id

Retrieve one audit, check status before trusting score and flags, handle 404 and 400.

Keep audits in sync with updated_after

Backfill once, then poll updated_after windows that overlap and upsert by id.

Make your first request