Build with the API

Errors & pagination

How the API reports errors and how to page through list responses.

This page covers the conventions shared across every Rightbrain endpoint: how errors come back, how to page through lists, and the headers you can rely on.

Errors

A failed request returns a non-2xx status and a JSON body under a detail key.

Most Rightbrain errors carry a machine-readable reason, a human-readable message, and — where relevant — an error-specific details object:

Error response
1{
2  "detail": {
3    "reason": "RESOURCE_NOT_FOUND",
4    "message": "Could not find task [0195d1ff-1f05-437a-95ac-6de8969cb47b]",
5    "resourceNotFoundError": {
6      "field": "task",
7      "value": "0195d1ff-1f05-437a-95ac-6de8969cb47b"
8    }
9  }
10}

Branch on reason (stable, machine-readable) rather than parsing message (human-readable, subject to change). Server errors (5xx) are deliberately opaque: they return reason: "INTERNAL_ERROR" with a generic message and no internal detail.

Authentication failures (401) are the exception to the detail envelope: they are rejected before the application layer and return {"error": {"code": 401, "status": "Unauthorized", "message": "Access credentials are invalid"}}, with no detail or reason.

Request validation

When a request body or query parameter fails schema validation, the API returns 422 with the standard FastAPI validation shape — a list of the fields at fault:

Validation error (422)
1{
2  "detail": [
3    {
4      "loc": ["query", "page_limit"],
5      "msg": "Input should be a valid integer, unable to parse string as an integer",
6      "type": "int_parsing"
7    }
8  ]
9}

Status codes

StatusMeaning
400Malformed request or a domain validation failure.
401Missing or invalid credentials.
403Authenticated, but not permitted on this project or resource.
404The resource does not exist (or you cannot see it).
409Conflict with the resource’s current state — for example, running an agent with a revision_id that does not match the session’s revision, or acting on an approval request that is no longer pending.
422Request failed schema validation (see above).
500Internal error; details are not exposed.

Pagination

List endpoints return a paginated envelope: a pagination object plus a results array.

Paginated response
1{
2  "pagination": {
3    "next_cursor": "0190a234-8dc6-6d08-aea9-928fcecad8f2",
4    "has_next": true,
5    "page_limit": 100
6  },
7  "results": [ ]
8}

Page with two query parameters:

cursor
string

Pass the previous response’s pagination.next_cursor to fetch the next page. Omit it for the first page.

page_limit
integer

The maximum number of items per page.

Stop when has_next is false (next_cursor will be null).

$curl "https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run?page_limit=100" \
>  -H "Authorization: Bearer YOUR_TOKEN"

Endpoints that return plain arrays

A few endpoints return a bare JSON array with no pagination envelope, because their result sets are small and fixed:

  • GET .../model
  • GET .../input_processor
  • GET .../task_forwarder_type
  • GET .../guardrail
  • GET .../api_key
  • GET .../task/{id}/share

Response headers

Task runs return two headers you can use for correlation and debugging:

  • x-task-run-id — the ID of the run just executed.
  • x-task-revision-id — the revision that served it.

Idempotency

Public webhook triggers accept an idempotency key so a retried delivery is not processed twice. Use it when the caller might resend the same event. See Triggers & runs for configuring public webhook invocation.

Run tasks via the API

The run endpoint, its response, and its headers.

Authentication

Get past 401 and 403 with the right credential.