Quickstart

Create a task

Author a structured AI function over the API — prompt in, typed output out.

A task is a structured AI function: a prompt with typed inputs, a chosen model, and a typed output. Agents call tasks as tools, and you can run them standalone from your own code. This quickstart creates one with a single API call.

What you’ll build: a task that reads a customer review and classifies its sentiment, with output fields ready to verify an attached product image once you enable file input. The next page runs it.

Before you start

Every request is authenticated with a bearer token. Create an API key under Settings → API Clients in your dashboard, then export it and your org and project IDs so the examples below run as-is.

$export RB_TOKEN="your-api-key"
$export RB_ORG="{org_id}"
$export RB_PROJECT="{project_id}"

For the full set of auth methods — OAuth 2.0, PKCE, task access tokens — see Authentication.

1

Pick a model

Tasks run on a model you choose. List the models available to your project and copy an id. So the same task can later verify an attached image, filter to vision-capable models with ?vision=image.

List vision-capable models
$curl "https://app.rightbrain.ai/api/v1/org/$RB_ORG/project/$RB_PROJECT/model?vision=image" \
>  -H "Authorization: Bearer $RB_TOKEN"

The endpoint returns a plain array. Each entry carries an id, a human-readable alias, supports_vision, and coarse price and speed tiers.

1[
2  {
3    "id": "ec217e75-72ea-4281-a1b8-cb7bd0ef9f41",
4    "name": "claude-sonnet-4-5",
5    "alias": "Claude Sonnet 4.5",
6    "provider": "anthropic",
7    "supports_vision": true,
8    "price": "average",
9    "speed": "fast"
10  }
11]

Save the id you want as RB_MODEL — the next step reads it. (llm_model_id requires the model’s id, not its name.)

$export RB_MODEL="{model_id}"
2

Create the task

Send a POST to the task endpoint. The user_prompt holds a {customer_review} placeholder — that becomes the task’s typed input. The output_format defines the structured response you get on every run.

$curl -X POST https://app.rightbrain.ai/api/v1/org/$RB_ORG/project/$RB_PROJECT/task \
>  -H "Authorization: Bearer $RB_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "Sentiment Analyzer",
>    "enabled": true,
>    "llm_model_id": "'"$RB_MODEL"'",
>    "system_prompt": "You are an expert product-review analyst specializing in e-commerce sentiment analysis and visual verification.",
>    "user_prompt": "Analyze the sentiment of this customer review, and describe the product image if one is attached, noting whether it matches the product in the review: {customer_review}",
>    "output_format": {
>      "sentiment": { "type": "string", "options": ["positive", "neutral", "negative"] },
>      "image_description": { "type": "string", "description": "A description of the product image, or \"N/A\" if none was provided" },
>      "image_match": { "type": "boolean", "description": "Whether the image matches the product described in the review" }
>    }
>  }'
3

Read the created task

The response is the task, created with an initial revision that is automatically active (active_revisions carries one revision at weight 1.0). Save the id — you’ll run this task on the next page.

1{
2  "id": "0195d1ff-1f05-437a-95ac-6de8969cb47b",
3  "name": "Sentiment Analyzer",
4  "enabled": true,
5  "output_modality": "json",
6  "active_revisions": [
7    {
8      "task_revision_id": "0195d1ff-1f42-f14e-8b65-641baf9dc32e",
9      "weight": 1.0
10    }
11  ]
12}

Give every output field a clear description and, where the answer is a fixed set, an options list. Constrained fields keep values inside a known set, which is what lets downstream code trust the output. See Tasks for nested and constrained output.

What’s next

Run and observe

Run your task over the API and read the response.

Build your first agent

Attach this task to an agent and run it with streaming.