Migrate document uploads from v1

Every v1 document call except POST /v1/ehr-ids has a v2 replacement, but no upload ports line for line: v2 never takes the file in the API request. You create the documents with a JSON request, then PUT each file to the upload URL the response gives you. For the general rules of v2 uploads, see Upload documents; for the other resources, see Migrate from v1.

Migration checklist

Copy this list into a ticket. Each item is one change to the code that calls the v1 document endpoints.

• Send requests to https://api.brellium.com/v2/... (v1 stays at /v1/...), with a v2 access token (Authenticate with OAuth2 client credentials). Mint one token per key and reuse it until it expires (Mint one access token and reuse it). POST /v2/oauth/token allows a burst of 20 requests per client_id, then one every 10 seconds; the 21st returns 429 with Retry-After.
• Stop sending files to the API. v1 takes the file as multipart/form-data. v2 takes a JSON request that describes the files (POST /v2/documents) and returns one upload URL per file. You then PUT each file's bytes to its URL. A multipart request to v2 fails with 400 INVALID_CONTENT_TYPE.
• Send content_type on every document, for example application/pdf. v1 reads the type from the file name's extension; v2 ignores the extension.
• Send extra form fields, such as ehr_source=sample-ehr, as a JSON object in external_metadata on each document. v1 stores every form field other than the file in the document's metadata.
• Stop sending doc_type. v2 sets it to default on every document and ignores any value you send.
• List several files in one POST /v2/documents (1 to 100 documents). Add "grouping": "group" when they belong together, as POST /v1/documents-multiple does; leave it out to have Brellium review each file on its own.
• After the PUT, there is nothing to confirm. The document moves from pending_upload to todo within seconds, and Brellium then processes it. To see its status, fetch the document, or the whole batch with ?group_id=.
• Each upload URL expires 15 minutes after the request (upload.expires_at). Send the PUT before then, with exactly the headers in upload.headers. v1 upload URLs last 1 hour and accept any Content-Type.
• If any file of a batch is still missing 24 hours after the batch was created, the whole batch expires: its pending_upload documents become upload_expired and its external_id values are released, so you can send the batch again. The resend creates a new batch, and you upload every file again.
• Set external_id on every document to make retries safe. v1 creates new documents on every retry. In v2, a request whose documents all carry the external_id values of one earlier batch returns that batch's documents instead of creating new ones. Documents whose files have not arrived come back with new upload URLs.
• Retrieve a document with GET /v2/documents/{document_id} instead of GET /v1/documents/:document_id. Your data is in external_metadata (v1 calls it metadata). The fields org_id, handler, audit_created and needs_audit are gone. To find a document's audits, use GET /v2/audits?documents=<document_id>.
• Handle the v2 error format. Every 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. request_id equals the x-request-id response header.

Upload one file

In v2, POST /v1/documents becomes two requests: create the document with POST /v2/documents, then PUT the file. v1 takes one file in the multipart part file and stores it before it answers.

Request

The v1 request:

curl --request POST "https://<your v1 host>/v1/documents" \
  --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN" \
  --form "file=@2026-09-23-session-note.pdf" \
  --form "ehr_source=sample-ehr"

curl --request POST "https://api.brellium.com/v2/documents" \
  --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "documents": [
      {
        "filename": "2026-09-23-session-note.pdf",
        "content_type": "application/pdf",
        "external_id": "EHR-NOTE-48213",
        "external_metadata": { "ehr_source": "sample-ehr" }
      }
    ]
  }'

const res = await fetch("https://api.brellium.com/v2/documents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRELLIUM_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    documents: [
      {
        filename: "2026-09-23-session-note.pdf",
        content_type: "application/pdf",
        external_id: "EHR-NOTE-48213",
        external_metadata: { ehr_source: "sample-ehr" },
      },
    ],
  }),
});
if (!res.ok) throw new Error(JSON.stringify((await res.json()).error));
console.log(await res.json());

import BrelliumClient from "@brellium/api-client";

const client = new BrelliumClient({ oAuth2: process.env.BRELLIUM_ACCESS_TOKEN });

const documentUploadList = await client.documents.create({
  documents: [
    {
      filename: "2026-09-23-session-note.pdf",
      content_type: "application/pdf",
      external_id: "EHR-NOTE-48213",
      external_metadata: { ehr_source: "sample-ehr" },
    },
  ],
});
console.log(documentUploadList);

import os

from brellium_api_client import BrelliumClient

client = BrelliumClient(o_auth2=os.environ["BRELLIUM_ACCESS_TOKEN"])

document_upload_list = client.documents.create(
    documents=[
        {
            "filename": "2026-09-23-session-note.pdf",
            "content_type": "application/pdf",
            "external_id": "EHR-NOTE-48213",
            "external_metadata": {"ehr_source": "sample-ehr"},
        },
    ],
)
print(document_upload_list.to_json())

curl --request PUT "$UPLOAD_URL" \
  --header "Content-Type: application/pdf" \
  --upload-file 2026-09-23-session-note.pdf \
  --write-out "HTTP %{http_code}\n"

import { readFile } from "node:fs/promises";

const res = await fetch(process.env.UPLOAD_URL!, {
  method: "PUT",
  headers: { "Content-Type": "application/pdf" },
  body: await readFile("2026-09-23-session-note.pdf"),
});
console.log(`HTTP ${res.status}`);

Response

v1 returns 201 with the id:

{
  "document_id": "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b"
}

v2 returns 201 with the list envelope; data[0] is the document and how to upload its file:

{
  "object": "list",
  "data": [
    {
      "document_id": "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
      "object": "document",
      "filename": "2026-09-23-session-note.pdf",
      "doc_type": "default",
      "status": "pending_upload",
      "group_id": "9c3f1a7e-5b2d-4e8f-a1c6-2d7b8e9f0a1b",
      "client": "",
      "provider": "",
      "service_code": "",
      "bcba": "",
      "us_state": "",
      "external_id": "EHR-NOTE-48213",
      "external_metadata": { "ehr_source": "sample-ehr" },
      "metadata": {
        "related_doc_ids": ["0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b"],
        "is_leading_doc": true
      },
      "upload_time": "2026-09-24T02:31:08.212Z",
      "created_at": "2026-09-24T02:31:08.212Z",
      "updated_at": "2026-09-24T02:31:08.212Z",
      "upload": {
        "url": "https://uploads.example.com/0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b?signature=...",
        "method": "PUT",
        "headers": { "Content-Type": "application/pdf" },
        "expires_at": "2026-09-24T02:46:08.212Z"
      }
    }
  ],
  "has_more": false
}

Behavior changes that break a direct port

• A 201 no longer means Brellium has the file. v1 stores the file before it answers, and the document starts at todo. A v2 document starts at pending_upload, and nothing happens until your PUT succeeds.
• The PUT can fail on its own. It returns a 403 in XML from the storage service when the URL has expired or the Content-Type differs from upload.headers. To get a new URL, send the same request again with the same external_id.
• Retry with external_id set. After a 500, a resend with the same external_id returns the same document instead of a new one (Safe retries). In v1, your retry creates a second document.
• Send the JSON types you want back in external_metadata. v1 receives every extra form field as text, so visit_number=3 arrives as "3".

Upload files that belong together

In v2, POST /v1/documents-multiple becomes one POST /v2/documents that lists every file and sets "grouping": "group", then a PUT of each file. v1 takes several files in the multipart part files and marks them as belonging together; "grouping": "group" marks the v2 documents the same way. In both versions, whether Brellium reviews them as one audit depends on your organization's setup.

Request

The v1 request:

curl --request POST "https://<your v1 host>/v1/documents-multiple" \
  --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN" \
  --form "files=@2026-09-23-session-note.pdf" \
  --form "files=@2026-09-23-data-sheet.csv" \
  --form "ehr_source=sample-ehr"

curl --request POST "https://api.brellium.com/v2/documents" \
  --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "documents": [
      {
        "filename": "2026-09-23-session-note.pdf",
        "content_type": "application/pdf",
        "external_id": "EHR-NOTE-48213",
        "external_metadata": { "ehr_source": "sample-ehr" }
      },
      {
        "filename": "2026-09-23-data-sheet.csv",
        "content_type": "text/csv",
        "external_id": "EHR-NOTE-48213-ATT-1",
        "external_metadata": { "ehr_source": "sample-ehr" }
      }
    ],
    "grouping": "group"
  }'

const res = await fetch("https://api.brellium.com/v2/documents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRELLIUM_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    documents: [
      {
        filename: "2026-09-23-session-note.pdf",
        content_type: "application/pdf",
        external_id: "EHR-NOTE-48213",
        external_metadata: { ehr_source: "sample-ehr" },
      },
      {
        filename: "2026-09-23-data-sheet.csv",
        content_type: "text/csv",
        external_id: "EHR-NOTE-48213-ATT-1",
        external_metadata: { ehr_source: "sample-ehr" },
      },
    ],
    grouping: "group",
  }),
});
if (!res.ok) throw new Error(JSON.stringify((await res.json()).error));
console.log(await res.json());

import BrelliumClient from "@brellium/api-client";

const client = new BrelliumClient({ oAuth2: process.env.BRELLIUM_ACCESS_TOKEN });

const documentUploadList = await client.documents.create({
  documents: [
    {
      filename: "2026-09-23-session-note.pdf",
      content_type: "application/pdf",
      external_id: "EHR-NOTE-48213",
      external_metadata: { ehr_source: "sample-ehr" },
    },
    {
      filename: "2026-09-23-data-sheet.csv",
      content_type: "text/csv",
      external_id: "EHR-NOTE-48213-ATT-1",
      external_metadata: { ehr_source: "sample-ehr" },
    },
  ],
  grouping: "group",
});
console.log(documentUploadList);

import os

from brellium_api_client import BrelliumClient

client = BrelliumClient(o_auth2=os.environ["BRELLIUM_ACCESS_TOKEN"])

document_upload_list = client.documents.create(
    documents=[
        {
            "filename": "2026-09-23-session-note.pdf",
            "content_type": "application/pdf",
            "external_id": "EHR-NOTE-48213",
            "external_metadata": {"ehr_source": "sample-ehr"},
        },
        {
            "filename": "2026-09-23-data-sheet.csv",
            "content_type": "text/csv",
            "external_id": "EHR-NOTE-48213-ATT-1",
            "external_metadata": {"ehr_source": "sample-ehr"},
        },
    ],
    grouping="group",
)
print(document_upload_list.to_json())

Response

v1 returns 201 with the ids, in the order of the files:

{
  "document_ids": [
    "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
    "5d4c3b2a-1908-4f7e-8d6c-5b4a39281706"
  ]
}

v2 returns 201 with one document per file. This sample is trimmed to the keys that differ between the two documents:

{
  "object": "list",
  "data": [
    {
      "document_id": "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
      "filename": "2026-09-23-session-note.pdf",
      "status": "pending_upload",
      "group_id": "9c3f1a7e-5b2d-4e8f-a1c6-2d7b8e9f0a1b",
      "external_id": "EHR-NOTE-48213",
      "metadata": {
        "related_doc_ids": [
          "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
          "5d4c3b2a-1908-4f7e-8d6c-5b4a39281706"
        ],
        "is_leading_doc": true
      },
      "upload": {
        "url": "https://uploads.example.com/0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b?signature=...",
        "method": "PUT",
        "headers": { "Content-Type": "application/pdf" },
        "expires_at": "2026-09-24T02:46:08.212Z"
      }
      /* ... the other document fields */
    },
    {
      "document_id": "5d4c3b2a-1908-4f7e-8d6c-5b4a39281706",
      "filename": "2026-09-23-data-sheet.csv",
      "status": "pending_upload",
      "group_id": "9c3f1a7e-5b2d-4e8f-a1c6-2d7b8e9f0a1b",
      "external_id": "EHR-NOTE-48213-ATT-1",
      "metadata": {
        "related_doc_ids": [
          "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
          "5d4c3b2a-1908-4f7e-8d6c-5b4a39281706"
        ],
        "is_leading_doc": false
      },
      "upload": {
        "url": "https://uploads.example.com/5d4c3b2a-1908-4f7e-8d6c-5b4a39281706?signature=...",
        "method": "PUT",
        "headers": { "Content-Type": "text/csv" },
        "expires_at": "2026-09-24T02:46:08.212Z"
      }
      /* ... the other document fields */
    }
  ],
  "has_more": false
}

Behavior changes that break a direct port

• Upload every file. v1 stores all files in one request; in v2 each PUT is separate, and a batch with a missing file expires.
• One POST /v2/documents request creates one batch: its documents share a group_id, and nothing can be added to it later. Send every file that belongs together in one request.
• If any file of a batch is still missing 24 hours after the batch was created, the whole batch expires: its pending_upload documents become upload_expired and its external_id values are released, so you can send the batch again. A document whose file did arrive gets no audit or coding evaluation unless it already has one. The resend creates a new batch, so upload every file again, including the ones that arrived (Incomplete batches expire after 24 hours).
• Retry with external_id values that all exist in one earlier batch. Resending only the documents whose files are missing also works. A request that mixes existing values with new ones, adds a document without an external_id, or carries values from two batches returns 409 EXTERNAL_ID_CONFLICT and creates nothing.

Get an upload URL

POST /v2/documents replaces POST /v1/documents/upload-url, the v1 call closest to v2: both take a JSON request and return an upload URL. v2 adds a required content_type, returns the full document, and can create up to 100 documents in one request.

Request

The v1 request:

curl --request POST "https://<your v1 host>/v1/documents/upload-url" \
  --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "filename": "2026-09-23-session-note.pdf",
    "doc_type": "session_note",
    "metadata": { "ehr_source": "sample-ehr" }
  }'

The v2 request:

curl --request POST "https://api.brellium.com/v2/documents" \
  --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "documents": [
      {
        "filename": "2026-09-23-session-note.pdf",
        "content_type": "application/pdf",
        "external_id": "EHR-NOTE-48213",
        "external_metadata": { "ehr_source": "sample-ehr" }
      }
    ]
  }'

const res = await fetch("https://api.brellium.com/v2/documents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRELLIUM_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    documents: [
      {
        filename: "2026-09-23-session-note.pdf",
        content_type: "application/pdf",
        external_id: "EHR-NOTE-48213",
        external_metadata: { ehr_source: "sample-ehr" },
      },
    ],
  }),
});
if (!res.ok) throw new Error(JSON.stringify((await res.json()).error));
console.log(await res.json());

import BrelliumClient from "@brellium/api-client";

const client = new BrelliumClient({ oAuth2: process.env.BRELLIUM_ACCESS_TOKEN });

const documentUploadList = await client.documents.create({
  documents: [
    {
      filename: "2026-09-23-session-note.pdf",
      content_type: "application/pdf",
      external_id: "EHR-NOTE-48213",
      external_metadata: { ehr_source: "sample-ehr" },
    },
  ],
});
console.log(documentUploadList);

import os

from brellium_api_client import BrelliumClient

client = BrelliumClient(o_auth2=os.environ["BRELLIUM_ACCESS_TOKEN"])

document_upload_list = client.documents.create(
    documents=[
        {
            "filename": "2026-09-23-session-note.pdf",
            "content_type": "application/pdf",
            "external_id": "EHR-NOTE-48213",
            "external_metadata": {"ehr_source": "sample-ehr"},
        },
    ],
)
print(document_upload_list.to_json())

Then PUT the file to upload.url, as in Upload one file.

Response

v1 returns 201 with the id and the upload URL:

{
  "document_id": "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
  "presigned_url": "https://uploads.example.com/...?signature=..."
}

The v2 response is the same as in Upload one file.

Behavior changes that break a direct port

• Send the PUT with the Content-Type from upload.headers. For a YAML file, that is application/yaml, even when the request said text/yaml.
• Each upload URL expires 15 minutes after the request (upload.expires_at); a v1 URL lasts 1 hour. For a new URL while the file has not arrived, send the same request again with the same external_id. Without external_id there is no way to get a new URL for the same document.
• Neither version has a confirm call. In both, the document moves from pending_upload to todo once the file arrives. v2 adds an expiry: a batch with a file that never arrives expires after 24 hours (upload_expired).

Retrieve a document

GET /v2/documents/{document_id} replaces GET /v1/documents/:document_id. The path keeps its shape. In the response, your metadata becomes external_metadata, and v2 adds fields.

Request

The v1 request:

curl "https://<your v1 host>/v1/documents/0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b" \
  --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN"

The v2 request:

curl "https://api.brellium.com/v2/documents/0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b" \
  --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN"

const res = await fetch(
  "https://api.brellium.com/v2/documents/0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
  { headers: { Authorization: `Bearer ${process.env.BRELLIUM_ACCESS_TOKEN}` } },
);
if (!res.ok) throw new Error(JSON.stringify((await res.json()).error));
console.log(await res.json());

import BrelliumClient from "@brellium/api-client";

const client = new BrelliumClient({ oAuth2: process.env.BRELLIUM_ACCESS_TOKEN });

const document = await client.documents.retrieve(
  "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
);
console.log(document);

import os

from brellium_api_client import BrelliumClient

client = BrelliumClient(o_auth2=os.environ["BRELLIUM_ACCESS_TOKEN"])

document = client.documents.retrieve("0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b")
print(document.to_json())

Response

The v1 response:

{
  "document_id": "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
  "org_id": "org_sample",
  "filename": "2026-09-23-session-note.pdf",
  "status": "complete",
  "handler": "sample_handler",
  "audit_created": true,
  "needs_audit": false,
  "metadata": { "ehr_source": "sample-ehr" }
}

The v2 response:

{
  "document_id": "0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b",
  "object": "document",
  "filename": "2026-09-23-session-note.pdf",
  "doc_type": "default",
  "status": "complete",
  "group_id": "9c3f1a7e-5b2d-4e8f-a1c6-2d7b8e9f0a1b",
  "client": "",
  "provider": "",
  "service_code": "",
  "bcba": "",
  "us_state": "",
  "external_id": "EHR-NOTE-48213",
  "external_metadata": { "ehr_source": "sample-ehr" },
  "metadata": {
    "related_doc_ids": ["0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b"],
    "is_leading_doc": true
  },
  "upload_time": "2026-09-24T02:31:08.212Z",
  "created_at": "2026-09-24T02:31:08.212Z",
  "updated_at": "2026-09-24T02:35:40.000Z"
}

Behavior changes that break a direct port

• A document you just created or changed can take a few seconds to appear at GET /v2/documents/{document_id}; until then you can get 404 or the earlier version. A create or update response is the current record, so use it instead of fetching the record again.
• An id that is not a UUID returns 400 VALIDATION_ERROR.

New in v2: list and update documents

• GET /v2/documents lists your organization's documents, newest first. Filter by group_id, status, doc_type, provider, client, created_after and created_before, or repeat document_id for a batch get; there is no external_id filter. A query string over 2,048 bytes is rejected with a bare 403 and no JSON body, so about 41 document_id values fit in one request; split a longer list across requests. For the pagination rules, see Page through and filter lists.
• PATCH /v2/documents/{document_id} changes external_id and external_metadata only. An omitted field keeps its value. A new external_metadata replaces the whole object, and external_id: null clears the id. A new external_id that another document in your organization already uses returns 409 EXTERNAL_ID_CONFLICT.

Statuses

Error changes

v1 answers with {"error": "..."}, {"msg": "..."} or plain text. Every v2 error is one JSON envelope, as in this 409 for an external_id conflict:

{
  "error": {
    "type": "conflict_error",
    "code": "EXTERNAL_ID_CONFLICT",
    "message": "Some external_id values in this request are already used by documents from another request. Retry a request with exactly the documents it was first sent with.",
    "details": { "external_ids": ["EHR-NOTE-48213"] },
    "request_id": "7f0b3c1e-2a4d-4b8e-9c11-5d6e7f8a9b0c"
  }
}

Every v2 error body carries request_id, which equals the x-request-id response header; send it to Brellium support when you report a problem. Branch on error.type and error.code, which are stable; message can change.

For every code and the retry rules, see Rate limits and errors.

Next