> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.rightbrain.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server. # Run tasks via the API > Call a Rightbrain task over REST — send task_input, attach files, select a revision, and read the run response, headers, and generated files. 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](/docs/api/authentication). ## Request body Send a JSON body with a single `task_input` object. Its keys match the `{placeholder}` variables in the task's prompt. > **Warning** > > The field is `task_input`, not `input_params`. A request without `task_input` fails validation. **`cURL`** ```bash title="cURL" 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." } }' ``` **`Python`** ```python title="Python" import requests url = "https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run" headers = {"Authorization": "Bearer YOUR_TOKEN"} payload = {"task_input": {"customer_review": "My toaster exploded during breakfast."}} response = requests.post(url, headers=headers, json=payload) response.raise_for_status() print(response.json()["response"]) ``` **`TypeScript`** ```typescript title="TypeScript" const url = "https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run"; const response = await fetch(url, { method: "POST", headers: { Authorization: "Bearer YOUR_TOKEN", "Content-Type": "application/json", }, body: JSON.stringify({ task_input: { customer_review: "My toaster exploded during breakfast." }, }), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const run = await response.json(); console.log(run.response); ``` ## 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`). #### Base64 in JSON Add a `task_files` array alongside `task_input`. Each entry has base64 `content` and a `filename`. **`Request body`** ```json title="Request body" { "task_input": { "customer_review": "My toaster exploded during breakfast." }, "task_files": [ { "filename": "toaster.jpeg", "content": "" } ] } ``` #### Multipart form data Send `task_input` as a JSON string field and each file under the `task_file` field. **`cURL`** ```bash title="cURL" curl -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run \ -H "Authorization: Bearer YOUR_TOKEN" \ -F 'task_input={"customer_review": "My toaster exploded during breakfast."}' \ -F 'task_file=@toaster.jpeg' ``` ## Query parameters | Parameter | Description | | -------------------- | ---------------------------------------------------------------------------------------- | | `revision_id` | Run a specific task revision. Mutually exclusive with `revision_tag`. | | `revision_tag` | Run the revision carrying this tag. Mutually exclusive with `revision_id`. | | `reporting_group` | Segment this run's metrics under a named reporting group (customer, feature, or cohort). | | `use_fallback_model` | Set 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](/docs/production/revisions). ## Response A successful run returns the task run object. Your model output is in `response`; everything else is metadata. **`Run response`** ```json title="Run response" { "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" } ``` | Field | Description | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `response` | The structured output matching the task's `output_format`. | | `id` | Unique ID of this run. Use it to fetch the run or its files later. | | `task_id` / `task_revision_id` | The task and the exact revision that served the run. | | `run_data.submitted` | The inputs as received. | | `files` | Files 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_tokens` | Token counts for the run. | | `input_processor_timing` / `llm_call_timing` | Time (seconds) spent pre-processing inputs and calling the model. | | `charged_credits` | Credits 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`** ```text title="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](/docs/api/errors-and-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 the generated output`** ```bash title="Download the generated output" # 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`** ```bash title="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](/docs/api/run-agents) Stream a multi-step agent run over Server-Sent Events. #### [TypeScript SDK](/docs/api/sdk) Call your tasks with a typed client instead of raw REST.