Migrate question set calls from v1

v1 has one question set endpoint, GET /v1/question-sets, which returns every question set of your organization in one array. In v2, two endpoints replace it: GET /v2/question_sets lists the sets one page at a time, and GET /v2/question_sets/{set_id} returns one set.

Migration checklist

Copy this list into a ticket. Each item is one change to the code that calls GET /v1/question-sets.

• Send requests to https://api.brellium.com/v2/... (v1 stays at /v1/...), with a v2 access token (Authenticate with OAuth2 client credentials).
• Change the path from /v1/question-sets (hyphen) to /v2/question_sets (underscore). The method stays GET.
• To fetch one set, for example the set an audit names in its set_id, call /v2/question_sets/{set_id} instead of searching the full v1 list.
• To fetch several known sets, repeat set_id in the list call: ?set_id=<id>&set_id=<id>.
• The list response is no longer a bare array of every set. Read the sets from data, and request the next page while has_more is true.
• Check any code that depends on the position of a set in the list. v2 returns the newest set first; v1 has no defined order.
• Rename the set's name field to set_name. Every other v1 field keeps its name.
• Treat null and "" as "no value" in question fields. v1 sends an empty string ("") for a missing question_type, severity, remediation or affirmation. v2 sends null, and remediation and affirmation can also be "".
• Make sure your code accepts the new fields: object, set_code, type, thresholds, created_at, updated_at on the set, and object on each question.
• Handle the v2 error format. Every error response is one JSON envelope: { "error": { "type", "code", "message", "param"?, "details"?, "request_id" } }. Handle 404 from GET /v2/question_sets/{set_id}. On 429 (too many requests), wait the number of seconds in the Retry-After header.

List all question sets

Request

v1 takes no parameters and ignores any you send. v2 takes cursor parameters and two filters.

- GET https://<your v1 host>/v1/question-sets
+ GET https://api.brellium.com/v2/question_sets?limit=100
  Authorization: Bearer $BRELLIUM_ACCESS_TOKEN

Response

v1 returns a bare array of every question set that is not deleted, each with its questions:

[
  {
    "set_id": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
    "name": "Progress Note Compliance",
    "questions": [
      {
        "question_id": "7d6c5b4a-3928-4170-a695-847362514f3e",
        "query": "Is the session note signed by the rendering provider?",
        "question_type": "default",
        "severity": "Critical",
        "affirmation": "",
        "remediation": "Ask the rendering provider to sign the note."
      },
      {
        "question_id": "6c5b4a39-2817-4069-9584-736251403f2e",
        "query": "Does the note document the service start and end times?",
        "question_type": "default",
        "severity": "Normal",
        "affirmation": "Service times are documented.",
        "remediation": ""
      },
      {
        "question_id": "5b4a3928-1706-4f58-8473-625140392e1d",
        "query": "Which program does this note belong to?",
        "question_type": "informational",
        "severity": "None",
        "affirmation": "",
        "remediation": ""
      }
    ]
  }
]

v2 returns the list envelope. Each item in data is a full question set, the same object GET /v2/question_sets/{set_id} returns:

{
  "object": "list",
  "data": [
    {
      "set_id": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
      "object": "question_set",
      "set_name": "Progress Note Compliance",
      "set_code": "PNC-1",
      "type": "treatment_plan",
      "thresholds": [
        { "flag_id": "5e4d3c2b-1a09-4f8e-9d7c-6b5a49382716", "score": 0.85 }
      ],
      "questions": [
        {
          "question_id": "7d6c5b4a-3928-4170-a695-847362514f3e",
          "object": "question",
          "query": "Is the session note signed by the rendering provider?",
          "question_type": "default",
          "severity": "Critical",
          "remediation": "Ask the rendering provider to sign the note.",
          "affirmation": null
        },
        {
          "question_id": "6c5b4a39-2817-4069-9584-736251403f2e",
          "object": "question",
          "query": "Does the note document the service start and end times?",
          "question_type": "default",
          "severity": "Normal",
          "remediation": null,
          "affirmation": "Service times are documented."
        },
        {
          "question_id": "5b4a3928-1706-4f58-8473-625140392e1d",
          "object": "question",
          "query": "Which program does this note belong to?",
          "question_type": "informational",
          "severity": "None",
          "remediation": null,
          "affirmation": null
        }
      ],
      "created_at": "2026-09-01T12:00:00.000Z",
      "updated_at": "2026-09-24T02:37:12.105Z"
    }
  ],
  "has_more": false
}

Field by field

The list envelope has these fields:

Each question set has these fields:

Each question in questions has these fields:

v1 sends the question fields in the order question_id, query, question_type, severity, affirmation, remediation; v2 sends remediation before affirmation. A JSON parser ignores field order.

Behavior changes that break a direct port

• v1 returns every question set. v2 returns at most limit sets per page (default 20, maximum 100): loop with starting_after until has_more is false. For the pagination loop, see Page through and filter lists. The samples below fetch the first page and the page after it, and print the two list envelopes.

  # First page, then the next page after the last set_id of the first page
  curl "https://api.brellium.com/v2/question_sets?limit=100" \
    --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN"
  curl --get "https://api.brellium.com/v2/question_sets" \
    --data-urlencode "limit=100" \
    --data-urlencode "starting_after=3c2b1a09-8f7e-4d6c-b5a4-938271605f4e" \
    --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN"
  

  bashCopyCopied

  const headers = { Authorization: `Bearer ${process.env.BRELLIUM_ACCESS_TOKEN}` };
  
  // First page, then the next page after the last set_id of the first page
  for (const params of [
    new URLSearchParams({ limit: "100" }),
    new URLSearchParams({
      limit: "100",
      starting_after: "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
    }),
  ]) {
    const res = await fetch(`https://api.brellium.com/v2/question_sets?${params}`, {
      headers,
    });
    if (!res.ok) throw new Error(JSON.stringify((await res.json()).error));
    console.log(await res.json());
  }
  

  tsCopyCopied

  import BrelliumClient from "@brellium/api-client";
  
  const client = new BrelliumClient({ oAuth2: process.env.BRELLIUM_ACCESS_TOKEN });
  
  // First page, then the next page after the last set_id of the first page
  console.log(await client.questionSets.list({ limit: 100 }));
  console.log(
    await client.questionSets.list({
      limit: 100,
      starting_after: "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
    }),
  );
  

  tsCopyCopied

  import os
  
  from brellium_api_client import BrelliumClient
  
  client = BrelliumClient(o_auth2=os.environ["BRELLIUM_ACCESS_TOKEN"])
  
  # First page, then the next page after the last set_id of the first page
  print(client.question_sets.list(limit=100).to_json())
  print(
      client.question_sets.list(
          limit=100, starting_after="3c2b1a09-8f7e-4d6c-b5a4-938271605f4e"
      ).to_json()
  )
  

  pythonCopyCopied

• v1 applies no sort to question sets, so their order is not defined. v2 sorts them by created_at, newest first, then by set_id.

• Within a set, v1 does not sort the questions either. v2 returns them in the set's configured order; questions without a position come last, sorted by question_id.

• Code that tests severity === "" (or similar) on a v1 question misses the v2 null, so test for both.

• v2 lists can take a few seconds to include a new or changed question set.

• Deleted question sets are left out in both versions.

Retrieve a question set

v1 has no endpoint that returns one question set, so you fetch the full list and search it for the set_id. In v2, GET /v2/question_sets/{set_id} returns the set directly.

- GET https://<your v1 host>/v1/question-sets
-   (then find the item whose set_id is 3c2b1a09-8f7e-4d6c-b5a4-938271605f4e)
+ GET https://api.brellium.com/v2/question_sets/3c2b1a09-8f7e-4d6c-b5a4-938271605f4e
  Authorization: Bearer $BRELLIUM_ACCESS_TOKEN

The response is one question set with the same fields as an item of the list data, so the field-by-field tables above apply unchanged.

{
  "set_id": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
  "object": "question_set",
  "set_name": "Progress Note Compliance",
  "set_code": "PNC-1",
  "type": "treatment_plan",
  "thresholds": [
    { "flag_id": "5e4d3c2b-1a09-4f8e-9d7c-6b5a49382716", "score": 0.85 }
  ],
  "questions": [ /* the three questions, as in the list response */ ],
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-24T02:37:12.105Z"
}

Retrieving one question set differs from searching the v1 list in three ways:

• The API returns 404 NOT_FOUND (Question set not found) when your organization has no question set with this id; another organization's id and a deleted set return 404 too. In v1 the set is missing from the array.
• A set_id that is not a UUID returns 400 VALIDATION_ERROR.
• A new or changed question set can take a few seconds to appear at GET /v2/question_sets/{set_id}; until then you can get a 404 or the previous version.

For code that joins a question set to an audit's responses and caches it by set_id, see Retrieve an audit's question set.

Batch get question sets by id

v1 has no filter: you search the full list. In v2, repeat set_id in the list call. The response is the list envelope. An id that matches no question set in your organization is left out, with no error.

- GET https://<your v1 host>/v1/question-sets
-   (then keep the items whose set_id is in your list)
+ GET https://api.brellium.com/v2/question_sets
+     ?set_id=3c2b1a09-8f7e-4d6c-b5a4-938271605f4e
+     &set_id=4d3c2b1a-9e8f-4a7b-8c6d-5e4f3a2b1c0d&limit=100
  Authorization: Bearer $BRELLIUM_ACCESS_TOKEN

The page size still applies: with more than 20 ids, send limit=100 or follow has_more. A query string over 2,048 bytes is rejected with a bare 403 and no JSON body, so about 46 set_id values fit in one request; split larger batches. For batch get by id, see Page through and filter lists.

Error changes

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