On this page
Signing in with the API key
- 1A 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.
- 2The other system sends the key in the header of every call:
Authorization: Bearer <key>. - 3Never send the key in the address (query string). It would end up in logs.
- 4If 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?
| Route | Used for | Who acts |
|---|---|---|
| Trigger | Another 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 |
| API | A 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
| Call | Returns |
|---|---|
GET /api/v1/cases | One 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/templates | Your company's templates that the API account may see. |
GET /api/v1/openapi.json | The 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
| Limit | Value |
|---|---|
| Reading calls | 120 per minute and key |
| Writing calls | 30 per minute and key (for later versions) |
| Simultaneous calls | at 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)
| Code | Meaning |
|---|---|
invalid_parameter | A parameter has an invalid value. |
unknown_parameter | The request contains a parameter that does not exist. |
invalid_limit | limit is not between 1 and 100. |
invalid_cursor | The cursor is invalid or expired. Start the list again from the beginning. |
idempotency_key_required | A writing command needs an idempotency key. Applies to later versions. |
unknown_command | This command does not exist. |
Sign-in and permissions (401, 403, 404)
| Code | Status | Meaning |
|---|---|---|
invalid_api_key | 401 | The key is missing, unknown or revoked. Bricksta answers the same way in all three cases. |
account_has_admin_rights | 403 | The API account has administration rights and is rejected. |
forbidden | 403 | The API account may not see or do this. |
not_found | 404 | The 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.
| Code | Status | Meaning |
|---|---|---|
conflict | 409 | The state has changed in the meantime. |
payload_too_large | 413 | The data sent is too large. |
unprocessable | 422 | The data is readable but does not fit the template's rules. |
read_only | 423 | The company is currently read-only. |
Too many calls (429)
| Code | Meaning |
|---|---|
rate_limited | The per-minute limit is reached. Wait for the time in Retry-After. |
too_many_concurrent_requests | Too many calls are running at once. Wait briefly and try again. |
Server-side errors (500 to 503)
| Code | Status | Meaning |
|---|---|---|
internal_error | 500 | Something went wrong at Bricksta. Try again later. |
timeout | 503 | The answer took too long. With Retry-After. |
temporarily_unavailable | 503 | Bricksta is briefly unavailable. With Retry-After. |
not_written | 503 | A writing command was not carried out. With Retry-After. |
outcome_unknown | 503 | It is unclear whether a writing command was carried out. No Retry-After: check first, then decide. |