Build with the API

Run tasks via the API

Execute a task with a single REST call and read back structured output.

A task is a stateless, versioned AI function. Run it by POSTing to its /run endpoint. The request carries your inputs; the response carries the structured output plus token, timing, and credit metrics.

POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run

All requests use bearer authentication — see Authentication.

Request body

Send a JSON body with a single task_input object. Its keys match the {placeholder} variables in the task’s prompt.

The field is task_input, not input_params. A request without task_input fails validation.

$curl -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run \
>  -H "Authorization: Bearer YOUR_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "task_input": {
>      "customer_review": "My toaster exploded during breakfast."
>    }
>  }'

Attach files

Tasks that accept image, PDF, or other file inputs take files in one of two ways. Whether a task accepts files, and which types, is set by its file_input_mode (none, image, pdf, image_or_pdf, or any).

Add a task_files array alongside task_input. Each entry has base64 content and a filename.

Request body
1{
2  "task_input": { "customer_review": "My toaster exploded during breakfast." },
3  "task_files": [
4    { "filename": "toaster.jpeg", "content": "<base64-encoded bytes>" }
5  ]
6}

Query parameters

ParameterDescription
revision_idRun a specific task revision. Mutually exclusive with revision_tag.
revision_tagRun the revision carrying this tag. Mutually exclusive with revision_id.
reporting_groupSegment this run’s metrics under a named reporting group (customer, feature, or cohort).
use_fallback_modelSet to true to force the task’s fallback model for this run.

If neither revision_id nor revision_tag is given, Rightbrain selects an active revision by its configured traffic weights (this is how A/B tests are served). See Versioning & revisions.

Response

A successful run returns the task run object. Your model output is in response; everything else is metadata.

Run response
1{
2  "task_id": "0195d1ff-1f05-437a-95ac-6de8969cb47b",
3  "task_revision_id": "0195d1ff-1f42-f14e-8b65-641baf9dc32e",
4  "response": {
5    "sentiment": "negative",
6    "image_match": true,
7    "image_description": "The image shows a severely damaged toaster..."
8  },
9  "run_data": {
10    "submitted": {
11      "customer_review": "My toaster exploded during breakfast..."
12    }
13  },
14  "files": [
15    {
16      "original_filename": "toaster.jpeg",
17      "stored_filename": "be8d9e69-9f2a-4bfd-bbf4-559d6b4eb5d0.jpeg",
18      "content_type": "image/jpeg",
19      "download_url": "/org/{org_id}/project/{project_id}/task/{task_id}/run/{run_id}/file/be8d9e69-9f2a-4bfd-bbf4-559d6b4eb5d0.jpeg",
20      "size_bytes": 48213
21    }
22  ],
23  "id": "0195d207-32bb-d03d-cfdc-f4516e9222c8",
24  "created": "2025-03-26T10:37:15.687874Z",
25  "input_tokens": 2051,
26  "output_tokens": 130,
27  "total_tokens": 2181,
28  "input_processor_timing": 0.0001468900591135025,
29  "llm_call_timing": 4.773190421052277,
30  "charged_credits": "9.00"
31}
FieldDescription
responseThe structured output matching the task’s output_format.
idUnique ID of this run. Use it to fetch the run or its files later.
task_id / task_revision_idThe task and the exact revision that served the run.
run_data.submittedThe inputs as received.
filesFiles attached to or generated by the run — objects with original_filename, stored_filename, content_type, download_url, and size_bytes.
input_tokens / output_tokens / total_tokensToken counts for the run.
input_processor_timing / llm_call_timingTime (seconds) spent pre-processing inputs and calling the model.
charged_creditsCredits consumed by the run.

Response headers

Every run response includes:

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

List and fetch runs

Run endpoints
GET  .../task/{task_id}/run                    list runs for a task (paginated)
GET  .../task/{task_id}/run/{run_id}           fetch a single run
GET  .../task/{task_id}/run/{run_id}/file/{file_name}   download a run file

List responses are paginated — see Errors & pagination. To download a file a run produced (for image, audio, PDF, or CSV output tasks), take the stored_filename from an entry in the run’s files array (or request its download_url directly).

cURL
$curl https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run/{run_id}/file/{file_name} \
>  -H "Authorization: Bearer YOUR_TOKEN" \
>  --output result.png
Run agents via the API

Stream a multi-step agent run over Server-Sent Events.

TypeScript SDK

Call your tasks with a typed client instead of raw REST.