How to Use the Brim API

Brim offers a powerful REST API that allows you to automate chart abstraction tasks, streamline your research workflows, and integrate Brim into your existing data infrastructure.

There are two main ways to use the Brim API:

Bulk upload and download, as described in this article.
By uploading and downloading single patient documents, as described in the single-note API article.

This guide provides an overview of how to get started, what you can do with the bulk API, and how to authenticate securely.

Why Use the Brim Bulk API?

You might use the API to:

Create a new project and add users
Clone an existing project
Create and update patients in bulk
Upload validation data
Run automated abstraction workflows
Retrieve generated and structured values
View and change which LLM a project uses
Track token usage for a project
Delete patients or notes that have aged out of your retention window
Integrate Brim with other systems
Monitor abstraction progress programmatically

Getting Access

To use the API, you need an API Token. You’ll find instructions for creating one here.

Most API actions use a project token, which only works for the project it was created in. Cloning a project requires an organization token.

Brim uses bearer token authentication. Include your token in the header of each API request like this:

Authorization: Bearer YOUR_TOKEN_HERE

Optional: Confirm the Project Name

To guard against sending a request to the wrong project, you can include the project’s name in an X-Brim-Project-Name header:

X-Brim-Project-Name: My Project

If the name doesn’t match the project ID in the request, Brim rejects the call with a 409 error and makes no changes. This is especially useful for scripts that upload, generate, or delete data across several projects.

What You Can Do With the Bulk API

Create a Project and Add Users

Create a new project
Add users with certain permissions

Clone a Project

Copy an existing project into a new project with a name you choose
Requires an organization token
Runs in the background. Check progress using the same task status check used for uploads and generation. When the clone finishes, the result includes the new project’s ID.
Works the same way as cloning a project in the Brim UI
API tokens are not copied. Create a new token for the cloned project.
Clones variables, notes, LLM configuration, labels, validation data.

Upload Data & Resources

Upload new or updated patient notes as a CSV.
Upload new or updated structured data fields as a CSV.
Upload new or updated variable and dependent variable definitions.
Upload new or updated resource or reference documents that can be used to create or optimize variables.
Upload validation data.

Manage LLM Settings

See which models are available for a project. Only active models your organization has access to are listed.
Change the default model used for regular and advanced generation
A project token can only view or change settings for its own project
Changes take effect right away

Run Generation Automatically

Generate labels for some or all patients and variables
Check the status of an upload or generation task while it runs

Export Generated Labels

Download generated and structured values
Filter an export to specific patients

Track Token Usage

See lifetime token usage for a project, broken out by input, output, cached input, and total tokens
Very recent usage may take a short time to appear

To learn more about how tokens are counted, see the LLM Token Usage articles.

Manage Data Retention

Some teams have a policy requiring clinical data to be removed after a set period. A few capabilities support this.

Find patients older than a given time period. Returns a list of patient MRNs in a project whose data falls outside the cutoff you specify. It only identifies patients and does not delete anything.
Delete patients. Permanently removes a list of patients from a project. The API accepts a list of MRNs rather than a single one. For each patient, this deletes:
- The patient notes and structured data
- Results associated with the patient
- Validation matches associated with the patient
Delete notes within a specified time range. Permanently removes notes based on their upload date

Because the delete patients endpoint takes a list of MRNs, you can pass the output of the patient lookup straight into it and run the whole retention cycle as one scheduled job.

Deletion is permanent. This applies to both patient and note deletion. There is no undo and no soft-delete window. Export anything you need to keep before you run it, and test against a non-production project first. Consider adding the X-Brim-Project-Name header to deletion calls so a mistyped project ID can’t remove data from the wrong project.

An example workflow for how to combine these capabilities is shown below.

Upload, generate, and download results with the API.

Example Script

You can see the various parts of our API in action by downloading and running our example python script.

Here's are some examples that you can find in the above sample script file + many more:

# Create a project, invite users with upload permission
python scripts/brim_utils.py \\
    --create-project "My Project" \\
    --users-to-add "user1@example.com,user2@example.com" \\
    --can-upload-permission

# Upload notes file (CSV) to existing project
python scripts/brim_utils.py --filepath notes.csv --project-id 123


# Upload structured data file (CSV) to existing project
python scripts/brim_utils.py --filepath structured.csv --structured-data --project-id 123


# Full workflow: create project, invite users, upload, generate, fetch results
python scripts/brim_utils.py --filepath notes.csv \\
    --create-project "My Project" \\
    --continue-if-project-exists \\
    --users-to-add "user1@example.com" \\
    --generate-after-upload \\
    --fetch-results \\
    --output-file results.csv

# Fetch existing project-wide results without uploading anything
python scripts/brim_utils.py --project-id 123 \\
    --fetch-results \\
    --output-file results.csv

# Fetch a detailed export instead of the default patient export
python scripts/brim_utils.py --project-id 123 \\
    --fetch-results \\
    --output-file results.csv \\
    --export-type detailed

Try It Out

You can explore and test all available endpoints at:

👉 https://demo.brimanalytics.com/api/docs#/

This interactive interface lets you try the API with your token and see example responses.

Need Help?

If you run into issues or have a question about what’s possible via the API, reach out to our team at any time by emailing support@brimanalytics.com.