Build with the API

Errors & pagination

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

This page covers shared error, pagination, response-header, and idempotency conventions. Endpoint-specific responses remain authoritative in the API reference.

Errors

Rightbrain uses several error forms:

  • Domain errors use detail.reason, detail.message, and sometimes an error-specific details field.
  • Request validation usually returns a detail array. Items can use either msg or message.
  • Some routes return a string detail.
  • Authentication failures use a top-level error object.
  • Gmail integration preconditions use detail.code.
  • MCP OAuth startup failures can be returned through redirect query parameters.

The Error reference documents these forms, common reason codes, run failures, and recovery guidance.

Status codes

StatusMeaning
400Malformed request or a domain validation failure.
401Missing or invalid credentials.
402Billing or credit state prevents execution. Resolve the account state before retrying.
403A permission check failed. The resource may also be hidden or unresolved by that check.
404A resource or route was not found. The response can be structured or a string detail.
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.
422Schema or application validation failed.
500Execution or internal failure. The body can be structured JSON, string JSON, or plain text.

Pagination

Most 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

Some endpoints return a bare JSON array with no pagination envelope:

  • GET .../model
  • GET .../input_processor
  • GET .../task_forwarder_type
  • GET .../guardrail
  • GET .../api_key
  • GET .../task/{id}/share
  • Skill source lists
  • Skill revision lists
  • Trigger-level event lists

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.