Build with the API

TypeScript SDK

Go from project setup to a typed task call in Next.js.

The @rightbrain/sdk client turns your tasks into typed functions. This walkthrough connects a Next.js form to a task with a product_name input and JSON output.

Before you start: use Node.js 22+, an existing Next.js App Router project, and a Rightbrain task. The examples use the @/ import alias; adjust paths to match your app. For other languages, use the REST API.

Next.js example

Follow the steps beside the code. Each file is complete: replace <task-id> with an ID from your generated types and use that task’s input fields.

  1. Install the SDK

    Run the install command in your app directory. You can also use pnpm add @rightbrain/sdk or yarn add @rightbrain/sdk.

  2. Sign in and generate task types

    Sign in, then select your organization, project, API key and tasks in init. The CLI writes credentials to .env and generates the Tasks type.

    The default output is src/generated/index.ts when src exists, otherwise generated/index.ts. Point the route’s import at that directory.

    Next.js loads .env for server code. DirectTransport does not load it or read environment variables itself.

  3. Keep credentials on the server

    Create a Client<Tasks> with DirectTransport. Pass the API key as accessToken, along with your organization, project and API base URL.

    This file runs on the server. Never put the key in a browser bundle or a NEXT_PUBLIC_ variable. Browser code calls your route below; applications using PublicTransport also need their own server proxy.

  4. Run the task from your route

    The generated task ID selects a typed runner. Its inputs match your task’s prompt variables, and result.response contains the JSON output.

    This sample route assumes your application’s authentication and access checks already protect it. Apply those checks before exposing a paid task to users.

  5. Handle loading and failures

    The hook sends the form input to your route. A failed HTTP response becomes a visible error, and loading is cleared after either outcome.

  6. Display the result

    The client component disables the button during the request and displays the returned JSON or an error. It never receives your API key.

    Import this component into a page in your app and submit the form to run the task.

npm install @rightbrain/sdk
npx rightbrain@latest login --url https://app.rightbrain.ai
npx rightbrain@latest init

Keep generated types current

Run npx rightbrain@latest generate after changing task schemas or the selected tasks. The CLI writes RB_ORG_ID, RB_PROJECT_ID and RB_API_KEY to .env; keep that file out of version control.

For a standalone Node script, load the environment with node --env-file=.env your-script.mjs or your runtime’s environment loader. DirectTransport also accepts a config object for additional fetch options. Credential options are covered in Authentication.

For a generic hook with inferred result types and request cancellation, use use-task.ts from the SDK demo.

Demo app

The Rightbrain SDK demo is a working Next.js app. It shows DirectTransport in a server route, PublicTransport in the browser, and a standalone Node script — each running real tasks that appear in your dashboard’s Runs view.

SDK or REST?

Use caseRecommended
TypeScript / Node / Next.js appsSDK — typed runners, ergonomic, transports
Other languages or frameworksREST API
Agents and SSE streamingRun agents via the API
Lightweight automation or scriptsREST API
Authentication

Create the API key the SDK uses.

Run tasks via the API

The REST endpoints behind the generated client.