Requests, lists, and errors

Field names and values

Built-in operations use snake_case for request and response fields. Record filters and sort also use those published names, for example data.start_time; internal field spellings are not accepted. App-defined fields keep the names explicitly published by that app. Dictionary keys and user content are not renamed.

Timestamp fields declare their units in the operation reference. Record timestamps use Unix milliseconds; ISO date-time strings remain strings where specified. Monetary fields on deals, products and product lines are Norwegian øre (100 øre = NOK 1). These records do not support selecting another currency.

Operation requests

The API base is https://api.brigg.app/v1. Discover operations with GET /operations, inspect one with GET /operations/{name}, and invoke it with POST /operations/{name}. Operation names are case-sensitive. Follow the released schema for each operation.

Send Content-Type: application/json and a JSON object matching the input schema. Responses match the output schema directly. Schema definitions use the terms input and output; those terms do not add wrappers to the wire format.

Operation names

Names follow product areas, such as customers.ListCompanies and meetings.ListMeetings. Use the exact published name in operation requests.

Operations published by workspace apps use apps.<app namespace>.<Operation>, for example apps.helpdesk.ReadMetrics. Discover the exact names available to your credential with GET https://api.brigg.app/v1/operations.

Lists and pagination

List contracts use items and an optional next_cursor:

{
  "items": [{ "id": "example_record" }],
  "next_cursor": "opaque_cursor"
}

Use the next cursor as the following request's cursor, keeping the same filters. Record-list operations default to 100 rows per page and accept a positive integer limit; they do not impose a fixed maximum. Other list operations document their own defaults, bounds and cursor support. Cursors are opaque: store and pass them unchanged.

The final page omits next_cursor. An empty result is { "items": [] }. Do not infer that the list is complete from the number of items in a page.

Errors

HTTP failures use a stable error code, a human-readable message, and optional structured details:

{
  "error": "rate_limited",
  "message": "The request limit has been reached."
}

Agents and integrations should branch on error and structured details, rather than parsing the message.

Request identifiers

The X-Request-Id response header identifies the request for diagnostics. Include it when reporting a failed call. Request IDs identify attempts; an idempotency key identifies the logical command across retries.

See safe retries and limits before retrying a command.

Iterate through a list on your server

The Node.js server helper exposes each row as an async iterator. It follows the server's cursors, preserves your filters and sort order, and keeps only the current page in memory:

import { createBriggClient } from "./brigg.mjs";
const brigg = createBriggClient({ apiKey: process.env.BRIGG_API_KEY!, baseUrl: "https://api.brigg.app" });

for await (const company of brigg.items("customers.ListCompanies", {
  filters: [{ field: "data.name", op: "contains", value: "Example" }],
  sort: { field: "data.name", direction: "asc" },
})) {
  console.log(company.id, company.data.name);
}

Use this with operations that return items and an optional next_cursor. Plain call(operation, input, options) returns the original response, which is useful when your application stores its own cursor. Commands require an explicit requestId in options; reuse it when retrying the same command. The helper does not automatically repeat an ambiguous command failure.

Synchronize records without duplicates

Use a resource's Upsert operation with external_ref: {namespace, id} for a permanent source-system match. Choose the namespace once and use the source system's record ID. The reference is scoped to the workspace, resource type and private/workspace ownership; it survives API key replacement and the retry-receipt window. It never guesses a match by email or name.

For larger files, start a resumable record import. Upload UTF-8 NDJSON with one complete Upsert request per line, then inspect progress and per-row outcomes. It applies the same grants, validation and webhooks as individual calls. Invalid rows are reported; interrupted work can resume without duplicating completed rows.