Run tasks via the API

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.

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).

{
  "task_input": { "customer_review": "My toaster exploded during breakfast." },
  "task_files": [
    { "filename": "toaster.jpeg", "content": "<base64-encoded bytes>" }
  ]
}

Query parameters

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.

{
  "task_id": "0195d1ff-1f05-437a-95ac-6de8969cb47b",
  "task_revision_id": "0195d1ff-1f42-f14e-8b65-641baf9dc32e",
  "response": {
    "sentiment": "negative",
    "image_match": true,
    "image_description": "The image shows a severely damaged toaster..."
  },
  "run_data": {
    "submitted": {
      "customer_review": "My toaster exploded during breakfast..."
    }
  },
  "files": [
    {
      "original_filename": "toaster.jpeg",
      "stored_filename": "be8d9e69-9f2a-4bfd-bbf4-559d6b4eb5d0.jpeg",
      "content_type": "image/jpeg",
      "download_url": "/org/{org_id}/project/{project_id}/task/{task_id}/run/{run_id}/file/be8d9e69-9f2a-4bfd-bbf4-559d6b4eb5d0.jpeg",
      "size_bytes": 48213
    }
  ],
  "id": "0195d207-32bb-d03d-cfdc-f4516e9222c8",
  "created": "2025-03-26T10:37:15.687874Z",
  "input_tokens": 2051,
  "output_tokens": 130,
  "total_tokens": 2181,
  "input_processor_timing": 0.0001468900591135025,
  "llm_call_timing": 4.773190421052277,
  "charged_credits": "9.00"
}

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

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. Uploaded files and generated files appear in files. For image, audio, PDF, or CSV output tasks, the generated output also has a response.download_url.

download_url is a path starting with /org/. Append it to https://app.rightbrain.ai/api/v1 and send the same Bearer authentication as the run request. It is not a public or signed URL. Resolving its leading slash against the host would drop /api/v1 and reach the wrong route. Missing or invalid authentication returns 401.

# DOWNLOAD_PATH is the response.download_url from the task run JSON.
curl --fail-with-body "https://app.rightbrain.ai/api/v1${DOWNLOAD_PATH}" \
  -H "Authorization: Bearer $RB_API_KEY" \
  --output result.csv

Alternatively, construct the file endpoint from the run ID and a stored_filename:

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