Integration & Automation

API: reading cases and tasks from another system

With the API, another system — your ERP, say — reads cases, tasks and templates from Bricksta. It signs in with an API key and needs no person for that. In version 1 the API can only read; it cannot change anything yet.

On this page

Signing in with the API key

  1. 1
    A person with organization administration creates an API access in the organization. Bricksta shows the key once while doing so; copy it straight to where the other system needs it.
  2. 2
    The other system sends the key in the header of every call: Authorization: Bearer <key>.
  3. 3
    Never send the key in the address (query string). It would end up in logs.
  4. 4
    If a key is lost or no longer needed, the API access is revoked. The key stops working immediately.

Every call is listed in the API access's run log: time, path, status and duration. Field contents are never in it.

What the API can do

An external system uses its API key to read your company's cases, tasks with all their fields (with field IDs and option IDs) and templates. The key acts as its own API account, a system account. It sees exactly what that account may see: its roles, private templates and the visibility of individual fields apply here too.

Bricksta rejects an API account that has administration rights (manage organization, members or templates). Give the API account only the rights the reading system needs.

API, trigger or AI assistant?

TriggerAnother system starts something in Bricksta from the outside, for example to start a case.The trigger, no person
AI assistant (MCP)Claude or ChatGPT work with Bricksta in a chat. More under Using Bricksta in Claude and ChatGPT.A person, with their rights
APIA system reads data from Bricksta, machine to machine.The API account, with a key

If Bricksta should report on its own when something happens, use the return channel: outbound webhooks.

The calls in version 1

GET /api/v1/casesOne page of cases. Filters: updated_since, template, status, field with value, limit (1 to 100) and cursor.
GET /api/v1/cases/{id}One case with all its tasks.
GET /api/v1/tasks/{id}One task with all fields, empty ones too, each with its IDs.
GET /api/v1/templatesYour company's templates that the API account may see.
GET /api/v1/openapi.jsonThe description of the API as OpenAPI 3.1. No sign-in needed.

Paging and reconciling

On GET /api/v1/cases, pass the next_cursor from the response as cursor in the next call. When next_cursor is empty (null), you are at the end. A case may be delivered at least once while paging, so possibly twice. Reconcile by id.

Changes from the last 30 seconds only appear on the next call. For a running sync, remember the largest updated_at of your last response and pass it as updated_since to ask only for what is new. Do not use the time of your call: changes from the 30 seconds before it were not in the response and would be missed. updated_at also changes when a task or a field value of the case changes.

Limits

Reading calls120 per minute and key
Writing calls30 per minute and key (for later versions)
Simultaneous callsat most 4 per key, 8 per company

If you exceed a limit, Bricksta answers 429 with a Retry-After header: wait that many seconds, then carry on. A company whose contract has ended can keep reading.

Error messages

On an error, Bricksta answers with application/problem+json (RFC 9457) and a code. Base the handling in the other system on the code. The codes are listed below by status.

Bad request (400)

invalid_parameterA parameter has an invalid value.
unknown_parameterThe request contains a parameter that does not exist.
invalid_limitlimit is not between 1 and 100.
invalid_cursorThe cursor is invalid or expired. Start the list again from the beginning.
idempotency_key_requiredA writing command needs an idempotency key. Applies to later versions.
unknown_commandThis command does not exist.

Sign-in and permissions (401, 403, 404)

invalid_api_key401The key is missing, unknown or revoked. Bricksta answers the same way in all three cases.
account_has_admin_rights403The API account has administration rights and is rejected.
forbidden403The API account may not see or do this.
not_found404The object does not exist. This also applies to objects of another company.

Writing commands (409 to 423)

These four codes only occur with writing commands of later versions. Version 1 only reads.

conflict409The state has changed in the meantime.
payload_too_large413The data sent is too large.
unprocessable422The data is readable but does not fit the template's rules.
read_only423The company is currently read-only.

Too many calls (429)

rate_limitedThe per-minute limit is reached. Wait for the time in Retry-After.
too_many_concurrent_requestsToo many calls are running at once. Wait briefly and try again.

Server-side errors (500 to 503)

internal_error500Something went wrong at Bricksta. Try again later.
timeout503The answer took too long. With Retry-After.
temporarily_unavailable503Bricksta is briefly unavailable. With Retry-After.
not_written503A writing command was not carried out. With Retry-After.
outcome_unknown503It is unclear whether a writing command was carried out. No Retry-After: check first, then decide.