# Quickstart
> Follow these steps to create your first API client, authenticate, and make your first call to the Rightbrain API.
## What is Rightbrain?
Rightbrain provides APIs to rapidly prototype, deploy, and scale Generative AI features. Define tasks using natural language, choose your models, and get auto-scaling API endpoints that integrate seamlessly into your workflows.
This documentation site provides machine-readable summaries to help you understand our API:
* [`/llms.txt`](/llms.txt): A concise overview of the documentation structure.
* [`/llms-full.txt`](/llms-full.txt): The complete documentation content, including the API reference, optimized for LLM consumption.
See the [AI Agent Guide](./ai-agent-guide) for more details.
## Quickstart Guide
Follow these steps to start using the Rightbrain API:
### Create an API Client
To interact with the API, you first need API credentials. You can create these in the Rightbrain dashboard:
1. Navigate to the **[API Clients settings page](https://app.rightbrain.ai/preferences?tab=api-clients)**.
2. Click "Create Client".
3. Fill in the details:
* **Client name:** A descriptive name for your application (e.g., "My Web App", "Backend Processor").
* **Description:** (Optional) Briefly describe what the client is used for.
* **Grant types:** Select the OAuth 2.0 flow(s) your application will use. For this quickstart, we'll use **Client Credentials**, which is suitable for server-to-server interactions or scripts.
* Choose `Client Credentials` for backend services or scripts.
* Choose `Authorization Code` (usually with PKCE) for web or mobile apps where a user logs in.
* You can select multiple grant types if needed.
4. Click **Save**.
5. **Important:** Your **Client Secret** will be displayed **only once**. Copy it immediately and store it securely alongside your **Client ID**. You will need both for authentication.
For a detailed explanation of which grant type to choose, see the [Authentication Overview](./auth).
### Obtain an Access Token (using Client Credentials)
Now, use your Client ID and Client Secret to get a temporary access token from the Rightbrain token endpoint. This example uses `curl` and the Client Credentials flow.
* **Token Endpoint URL:** `https://oauth.rightbrain.ai/oauth2/token`
```bash
# Replace with your actual Client ID and Secret from Step 1
CLIENT_ID=""
CLIENT_SECRET=""
# Request the token using Client Credentials grant
TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
-d "grant_type=client_credentials" \
https://oauth.rightbrain.ai/oauth2/token | jq -r '.access_token')
# Check if the token was obtained (optional)
# echo "Token: $TOKEN"
```
This command authenticates using your credentials (`-u`) and requests a token (`-d grant_type=...`). The access token is extracted from the JSON response using `jq` and stored in the `TOKEN` variable.
### Make Your First API Call
With the access token stored in the `TOKEN` variable, you can now make authenticated requests to the Rightbrain API. Include the token in the `Authorization` header using the `Bearer` scheme.
Replace `` with the actual endpoint you want to call (e.g., from the [API Reference](/api-reference)).
```bash
# Ensure TOKEN variable is set from Step 2
curl -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{"parameter": "value"}' \
```
For more details on how the `Authorization` header works, see [Calling the API](./auth-calling-api).
## Next Steps
You've successfully authenticated and made a call! Now you can:
* Explore the detailed guides for different **[Authentication methods](./auth)**.
* Dive into the **[API Reference](/api-reference)** to discover available endpoints.
* Check out the **[Guides](/integrations-overview)** section for connecting Rightbrain with other services.
# Calling the API
> Learn how to include your OAuth 2.0 access token in the Authorization header to make authenticated calls to the Rightbrain API.
## Using Your Access Token
Once you have successfully obtained an access token using one of the [supported OAuth 2.0 grant types](./auth), you need to include it in your requests to the Rightbrain API.
Rightbrain expects the access token to be sent in the `Authorization` HTTP header using the `Bearer` authentication scheme.
**Header Format:**
```text
Authorization: Bearer
```
Replace `` with the actual `access_token` value you received from the token endpoint.
**Example API Call (`curl`):**
This generic example shows how to include the `Authorization` header. Remember to replace:
* `${TOKEN}` with your actual access token (or use the variable if set).
* `` with the specific Rightbrain API endpoint you want to call.
* The HTTP method (`-X POST`) and body (`-d '...'`) as required by the specific endpoint.
```bash
# Ensure your access token is stored in the TOKEN variable or replace ${TOKEN}
TOKEN=""
curl -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{"parameter": "value"}' \
```
## Important Considerations
* **Expiration:** Access tokens have a limited lifetime. If you receive an authentication error (like a 401 Unauthorized), your token may have expired.
* **Refreshing (Authorization Code / PKCE):** If you obtained a refresh token (using the Authorization Code or PKCE flow with the `offline_access` scope), use the refresh token grant to get a new access token. Refer back to the specific grant type documentation ([Authorization Code](./auth-code#token-refresh), [PKCE](./auth-pkce#token-refresh)) for details.
* **No Refreshing (Client Credentials):** Tokens obtained via the Client Credentials grant cannot be refreshed. You must request a completely new token when the old one expires using the [Client Credentials flow](./auth-client-credentials).
* Keep your access tokens secure, just like passwords. Avoid exposing them in client-side code or insecure logs.
# Authentication Overview
> Understand the different OAuth 2.0 grant types supported by Rightbrain and when to use each for authenticating your API requests.
## Choosing an Authentication Method
Rightbrain utilizes the industry-standard **OAuth 2.0** framework for authentication and authorization. To interact with the Rightbrain API, your application must first obtain an access token using one of the supported OAuth 2.0 grant types (flows). The access token is then included in the `Authorization` header of your API requests.
The appropriate grant type depends on the nature of your application. Select the grant type that best fits your application's architecture and security requirements, then follow the detailed steps on the corresponding page.
**Best for:** Machine-to-machine (M2M) applications like backend services, daemons, or scripts acting on their own behalf.
* **Credentials:** Client ID, Client Secret
* **User Interaction:** None
* **Refreshable:** No
**Best for:** Traditional server-side web applications where a user logs in and the application can securely store a Client Secret.
* **Credentials:** Client ID, Client Secret, Redirect URI
* **User Interaction:** Yes (login & consent)
* **Refreshable:** Yes (requires `offline_access` scope)
**Best for:** Public clients (SPAs, mobile/desktop apps) that cannot securely store a Client Secret. Recommended for all clients.
* **Credentials:** Client ID, Redirect URI
* **User Interaction:** Yes (login & consent)
* **Refreshable:** Yes (requires `offline_access` scope)
# Client Credentials Grant
> Learn how to use the OAuth 2.0 Client Credentials flow for machine-to-machine authentication where no user interaction is required.
## OAuth 2.0 Client Credentials Grant
This grant type is used for **machine-to-machine (M2M)** authentication. It allows your application (the client) to obtain an access token using its own credentials (Client ID and Client Secret) without the presence or permission of an end-user.
**Use Case:**
* Server-side services or daemons making API calls on their own behalf (not on behalf of a specific user).
* Automated scripts or backend processes interacting with the API.
* CLI tools.
**Prerequisites:**
* You have created an API Client in the Rightbrain dashboard.
* You have your **Client ID** and **Client Secret** for this API Client.
* **Client ID**: Found on the **Account** page in the Rightbrain dashboard.
* **Client Secret**: Provided during API Client creation.
The Client Secret is highly sensitive. Store it securely and never expose it in client-side code. If lost, you must regenerate it.
### Request Access Token
* Your application makes a direct **POST** request to the Rightbrain Token Endpoint.
* **URL:** `https://oauth.rightbrain.ai/oauth2/token`
* **Authentication:** Use HTTP Basic Authentication with your Client ID as the username and Client Secret as the password.
* **Headers:**
* `Content-Type: application/x-www-form-urlencoded`
* **Body (Form Data):**
* `grant_type=client_credentials`
* (Optional) `scope=`: If your client needs specific scopes beyond default access, include them here.
* **Example Request (`curl`):**
This command uses the `-u` flag for Basic Authentication and requests a token using the `client_credentials` grant.
```bash
# Set your credentials (replace placeholders or use environment variables)
CLIENT_ID=""
CLIENT_SECRET=""
TOKEN=$(curl -s -u \"$CLIENT_ID:$CLIENT_SECRET\" \
-d \"grant_type=client_credentials\" \
https://oauth.rightbrain.ai/oauth2/token | jq -r '.access_token')
# Example: Print the token to verify
# echo $TOKEN
```
# Authorization Code Grant
> Learn how to use the standard OAuth 2.0 Authorization Code flow for applications that can securely store a client secret.
## OAuth 2.0 Authorization Code Grant
This flow is designed for **confidential clients** – applications (typically traditional web applications) that run on a server and can securely store a **Client Secret**. It allows users to grant your application access to their Rightbrain data without sharing their credentials directly with your application.
**Use Case:** Server-side web applications where the backend can securely handle the Client Secret.
**Prerequisites:**
* You have registered your application in the Rightbrain dashboard.
* You have obtained a **Client ID** and **Client Secret**.
* You have registered one or more **Redirect URIs** for your application in the dashboard.
### Initiate Authorization Request
* Redirect the user's browser to the Rightbrain Authorization Endpoint.
* **Method:** `GET`
* **URL:** `https://oauth.rightbrain.ai/oauth2/auth`
* **Query Parameters:**
* `response_type=code`: Specifies the desired flow.
* `client_id=`: Your application's Client ID.
* `redirect_uri=`: The URL where Rightbrain will redirect the user back after authorization. Must match one of the registered URIs.
* `state=`: (Recommended) A random string generated by your application to prevent CSRF attacks. You should store this value temporarily (e.g., in the user's session) to verify it later.
* `scope=`: (Optional) A space-separated list of permissions your application is requesting.
To receive a refresh token, you **must** include the `offline_access` scope in your request.
* **Example URL (requesting refresh token, broken down):**
```
https://oauth.rightbrain.ai/oauth2/auth?
response_type=code&
client_id=YOUR_CLIENT_ID&
redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&
state=xyzABC123&
scope=offline_access
```
* **Example URL (URL-encoded):**
```
https://oauth.rightbrain.ai/oauth2/auth?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&state=xyzABC123&scope=offline_access
```
### User Authorizes Application
* The user is prompted to log in to Rightbrain (if not already logged in).
* The user is shown a consent screen asking them to authorize your application.
### Receive Authorization Code
* If the user grants authorization, Rightbrain redirects the user's browser back to your specified `redirect_uri`.
* The redirect URL will include:
* `code=`: A short-lived, single-use authorization code.
* `state=`: The same state value you provided in step 1.
Your application **must** verify that the received `state` value matches the one stored from step 1 to prevent Cross-Site Request Forgery (CSRF) attacks.
* **Example Callback URL:**
```text
https://your-app.com/callback?code=AUTHORIZATION_CODE_HERE&state=xyzABC123
```
### Exchange Authorization Code for Tokens
* Your application backend makes a POST request to the Rightbrain Token Endpoint.
* **Method:** `POST`
* **URL:** `https://oauth.rightbrain.ai/oauth2/token`
* **Authentication:** Use HTTP Basic Authentication (Client ID as username, Client Secret as password).
* **Body (Form Data):**
* `grant_type=authorization_code`: Specifies the grant type.
* `code=`: The code received in step 3.
* `redirect_uri=`: The same redirect URI used in step 1.
* `client_id=`: Your application's Client ID.
* `client_secret=`: Your application's Client Secret.
* **Example (`curl`):**
```bash
CODE=""
REDIRECT_URI="https://your-app.com/callback"
CLIENT_ID="YOUR_CLIENT_ID"
CLIENT_SECRET="YOUR_CLIENT_SECRET"
curl -s -X POST \
-u "${CLIENT_ID}:${CLIENT_SECRET}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=${CODE}" \
-d "redirect_uri=${REDIRECT_URI}" \
https://oauth.rightbrain.ai/oauth2/token | jq
```
### Receive Tokens
* Rightbrain validates the request and responds with a JSON object containing:
* `access_token`: The token used to make authenticated API calls.
* `token_type`: Typically `Bearer`.
* `expires_in`: The lifetime of the access token in seconds.
* `refresh_token`: (Optional) Issued only if the `offline_access` scope was requested and granted. Used to obtain new access tokens without user interaction.
### Call the API
* Use the obtained `access_token` in the `Authorization: Bearer ` header to make requests to the Rightbrain API on behalf of the user.
## Token Refresh
To obtain a new access token using a refresh token, make a POST request to the token endpoint:
### Make POST Request
* **Method:** `POST`
* **URL:** `https://oauth.rightbrain.ai/oauth2/token`
* **Authentication:** Use HTTP Basic Authentication (Client ID and Secret).
* **Body:**
* `grant_type=refresh_token`
* `refresh_token=`
* `client_id=`
* `client_secret=`
* **Example (`curl`):**
```bash
REFRESH_TOKEN=""
CLIENT_ID="YOUR_CLIENT_ID"
CLIENT_SECRET="YOUR_CLIENT_SECRET"
curl -s -X POST \
-u "${CLIENT_ID}:${CLIENT_SECRET}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=${REFRESH_TOKEN}" \
https://oauth.rightbrain.ai/oauth2/token | jq
```
### Receive New Tokens
* The response will contain a new `access_token` and potentially a new `refresh_token`.
# Authorization Code Grant with PKCE
> Learn how to use the OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange) for enhanced security, especially for applications that cannot securely store a client secret.
## OAuth 2.0 Authorization Code Grant with PKCE
PKCE (Proof Key for Code Exchange, pronounced "pixie") is an extension to the Authorization Code flow that enhances security by mitigating authorization code interception attacks. It's **highly recommended** for **public clients** – applications like Single Page Applications (SPAs) or mobile apps that cannot securely store a Client Secret. It can also be used by confidential clients for added security.
**Use Case:** SPAs, mobile apps, desktop apps, or any client that cannot guarantee the confidentiality of a Client Secret.
**Prerequisites:**
* You have registered your application in the Rightbrain dashboard.
* You have obtained a **Client ID**.
* You have registered one or more **Redirect URIs** for your application in the dashboard.
* Your application can generate a cryptographically random string (code verifier) and derive a SHA-256 hash (code challenge) from it.
### Generate Code Verifier and Challenge
* Before starting the flow, your application generates a high-entropy cryptographic random string called the `code_verifier` (between 43 and 128 characters, using A-Z, a-z, 0-9, -, ., \_, \~).
* Your application then creates a `code_challenge` by BASE64URL-encoding the SHA-256 hash of the `code_verifier`.
You **must** store the generated `code_verifier` securely (e.g., in session storage or memory) as it will be needed in Step 5 to exchange the authorization code for tokens.
### Initiate Authorization Request
* Redirect the user's browser to the Rightbrain Authorization Endpoint.
* **Method:** `GET`
* **URL:** `https://oauth.rightbrain.ai/oauth2/auth`
* **Query Parameters:**
* `response_type=code`: Specifies the desired flow.
* `client_id=`: Your application's Client ID.
* `redirect_uri=`: The URL where Rightbrain will redirect the user back.
* `state=`: (Recommended) A random string to prevent CSRF attacks.
* `code_challenge=`: The BASE64URL-encoded SHA-256 hash of the code verifier (from Step 1).
* `code_challenge_method=S256`: Specifies the hashing method used (Rightbrain requires S256).
* `scope=`: (Optional) A space-separated list of permissions.
To receive a refresh token, you **must** include the `offline_access` scope.
* **Example URL (formatted for readability):**
```
https://oauth.rightbrain.ai/oauth2/auth?
response_type=code&
client_id=YOUR_CLIENT_ID&
redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&
state=xyzABC123&
scope=offline_access&
code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGxEaFeXBQ&
code_challenge_method=S256
```
* **Example URL (URL-encoded):**
```
https://oauth.rightbrain.ai/oauth2/auth?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&state=xyzABC123&scope=offline_access&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGxEaFeXBQ&code_challenge_method=S256
```
### User Authorizes Application
* Same as the standard Authorization Code flow (user logs in and grants consent).
### Receive Authorization Code
* Same as the standard Authorization Code flow (Rightbrain redirects to your `redirect_uri` with `code` and `state`).
Your application **must** verify that the received `state` value matches the one stored from Step 2 to prevent Cross-Site Request Forgery (CSRF) attacks.
### Exchange Code for Tokens
* Your application makes a POST request to the Rightbrain Token Endpoint.
* **Method:** `POST`
* **URL:** `https://oauth.rightbrain.ai/oauth2/token`
* **Headers:**
* `Content-Type: application/x-www-form-urlencoded`
* **Body (Form Data):**
* `grant_type=authorization_code`: Specifies the grant type.
* `code=`: The code received in step 4.
* `redirect_uri=`: The same redirect URI used in step 2.
* `client_id=`: Your application's Client ID.
* `code_verifier=`: The original plain-text code verifier generated in Step 1.
Note that the `client_secret` is **NOT** included in this request when using PKCE with public clients.
* **Example (`curl`):**
```bash
CODE=""
CODE_VERIFIER=""
REDIRECT_URI="https://your-app.com/callback"
CLIENT_ID="YOUR_CLIENT_ID"
curl -s -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=${CODE}" \
-d "redirect_uri=${REDIRECT_URI}" \
-d "client_id=${CLIENT_ID}" \
-d "code_verifier=${CODE_VERIFIER}" \
https://oauth.rightbrain.ai/oauth2/token | jq
```
### Receive Tokens
* Rightbrain verifies the `code_verifier` against the `code_challenge` sent earlier. If valid, it responds with:
* `access_token`: The token used to make authenticated API calls.
* `token_type`: Typically `Bearer`.
* `expires_in`: The lifetime of the access token in seconds.
* `refresh_token`: (Optional) Issued only if the `offline_access` scope was requested and granted.
### Call the API
* Use the obtained `access_token` in the `Authorization: Bearer ` header.
## Token Refresh
If you received a refresh token, you can use it to get a new access token when the current one expires. Make a POST request to the token endpoint:
### Make POST Request
* **Method:** `POST`
* **URL:** `https://oauth.rightbrain.ai/oauth2/token`
* **Headers:**
* `Content-Type: application/x-www-form-urlencoded`
* **Body:**
* `grant_type=refresh_token`
* `refresh_token=`
* `client_id=`
Note: `client_secret` is **NOT** sent for public clients, and `code_verifier` is not needed for token refresh.
* **Example (`curl`):**
```bash
REFRESH_TOKEN=""
CLIENT_ID="YOUR_CLIENT_ID"
curl -s -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=${REFRESH_TOKEN}" \
-d "client_id=${CLIENT_ID}" \
https://oauth.rightbrain.ai/oauth2/token | jq
```
### Receive New Tokens
* The response will contain a new `access_token` and potentially a new `refresh_token`.
# AI Agent Guide
> Provides key URLs, authentication details, API reference links, and machine-readable documentation paths for AI agents.
## Information for AI Agents
This page provides essential information to help you understand and interact with the Rightbrain API.
To efficiently understand the structure and content of this documentation, please use the following files hosted at the root of this documentation site:
* `/llms.txt`: Contains a concise summary of each documentation page and its URL.
* `/llms-full.txt`: Provides the full, token-optimized content of the documentation, including the complete API Reference.
**Authentication:**
* All API requests require an `access_token` included in the `Authorization: Bearer ` header.
* Refer to the [Authentication Overview](./auth) to understand the different methods for obtaining an access token (Client Credentials, Authorization Code, PKCE).
* The [Client Credentials Grant](./auth-client-credentials) is typically used for autonomous agent interactions.
The Client Credentials Grant is generally the most suitable method for agents authenticating on their own behalf without user interaction.
* Learn how to structure the request in [Calling the API](./auth-calling-api).
**API Reference:**
* The full [API Reference](/api-reference) provides details on all available endpoints, request parameters, and response schemas.
By utilizing the `llms-full.txt` file and the API Reference, you should have the necessary information to construct valid API calls for Rightbrain Tasks.
# Integrations Overview
> Learn how to integrate Rightbrain Tasks with services like n8n, Make.com, Zapier, and more.
## Connecting Rightbrain
This section provides guides and examples for integrating Rightbrain Tasks into various third-party services and automation platforms.
Automate workflows, trigger tasks from external events, and send task results to other applications.
Guide coming soon!
Guide coming soon!
Guide coming soon!
Don't see your tool? Let us know by opening an issue!
Check back soon for detailed integration instructions.
# List All Tags
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/{entity_type}/tag
```
Retrieve a paginated list of all tags for a specific entity type.
Returns all tags that:
- Belong to the specified project
- Are of the specified entity_type (task or task_revision)
- Are accessible to the current user
- Are root-level tags (no parent)
Child tags are included in the `children` field of their parent tags.
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- EntityType (required): The type of entity to tag
## Query Parameters
- PageLimit (optional): The maximum number of items to return per page. Defaults to `100` if not specified.
- Cursor (optional): A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results.
## Response Body
- 200: Successfully retrieved tags
- 400: Bad Request - Invalid parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to list tags
- 404: Not Found - Project not found
- 422: Unprocessable Entity - Query parameter validation failed
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/tag \
-H "Authorization: Bearer "
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
# Create New Tag
```http
POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/{entity_type}/tag
Content-Type: application/json
```
Create a new tag for organizing and filtering Tasks or Task Revisions.
Tags provide a flexible way to organize your Tasks and Task Revisions. They can be used to:
- Group related Tasks (e.g., 'production', 'staging', 'experimental')
- Filter Tasks in the UI and API responses
- Create hierarchical organizations with parent-child relationships
- Mark Tasks for specific workflows or stages
Tags must have alphanumeric names (max 15 characters) and can optionally be organized in a hierarchy using parent_id.
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- EntityType (required): The type of entity to tag
## Response Body
- 200: Successfully created tag
- 400: Bad Request - Invalid path parameters or tag data
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to create tags
- 404: Not Found - Project not found
- 422: Unprocessable Entity - Tag validation failed
## Examples
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/tag \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "staging",
"entity_type": "task",
"parent_id": "01909843-3596-da54-4756-28af46917e74"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"entity_type": "task"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"entity_type": "task"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"entity_type": "task"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"entity_type": "task"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"entity_type": "task"
}'
```
# Get Tag Details
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/{entity_type}/tag/{tag_id}
```
Retrieve detailed information about a specific tag.
Returns:
- Tag metadata (id, name, creation time)
- Parent-child relationship information
- Project association
- Entity type (task/task_revision)
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- EntityType (required): The type of entity to tag
- TagId (required): The unique identifier (UUID) of the tag to operate on
## Response Body
- 200: Successfully retrieved tag details
- 400: Bad Request - Invalid path parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to view tag
- 404: Not Found - Tag not found
- 422: Unprocessable Entity - Path parameter validation failed
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/tag/01909843-3596-da54-4756-28af46917e74 \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag/:tag_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag/:tag_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag/:tag_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag/:tag_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag/:tag_id \
-H "Authorization: Bearer "
```
# Update Tag
```http
POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/{entity_type}/tag/{tag_id}
Content-Type: application/json
```
Update an existing tag's properties.
Currently supports:
- Renaming the tag (must remain alphanumeric, max 15 characters)
- Cannot modify parent-child relationships after creation
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- EntityType (required): The type of entity to tag
- TagId (required): The unique identifier (UUID) of the tag to operate on
## Response Body
- 200: Successfully updated tag
- 400: Bad Request - Invalid path parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to update tag
- 404: Not Found - Tag not found
- 422: Unprocessable Entity - Tag update validation failed
## Examples
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/tag/01909843-3596-da54-4756-28af46917e74 \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "beta"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag/:tag_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag/:tag_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag/:tag_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag/:tag_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/tag/:tag_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
# Delete Tag
```http
DELETE https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/tags/{tag_id}
```
Permanently delete a tag.
Notes:
- Deleting a parent tag will also delete all child tags
- References to the deleted tag will be removed from all Tasks/Task Revisions
- This operation cannot be undone
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- TagId (required): The unique identifier (UUID) of the tag to operate on
## Response Body
- 204: Tag successfully deleted
- 400: Bad Request - Invalid tag ID
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to delete tag
- 404: Not Found - Tag not found
- 422: Unprocessable Entity - Path parameter validation failed
## Examples
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/tags/01909843-3596-da54-4756-28af46917e74 \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/tags/:tag_id \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/tags/:tag_id \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/tags/:tag_id \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/tags/:tag_id \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/tags/:tag_id \
-H "Authorization: Bearer "
```
# List Tasks
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task
```
List all Tasks in the project with pagination support.
Returns a paginated list of Tasks with their basic information:
- Task ID and metadata
- Active revision status
- Latest modification time
- Tags
Use the page_limit and cursor parameters to navigate through the results.
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Query Parameters
- Name (optional): Filter tasks by name (case-insensitive partial match).
- TagId (optional): Filter tasks by tag ID.
- IncludeTests (optional): Include test revisions
- Cursor (optional): Pagination cursor for the next page of results.
- PageLimit (optional): Maximum number of tasks to return per page.
## Response Body
- 200: Successful Response
- 400: Bad Request - Invalid pagination parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to list tasks
- 422: Unprocessable Entity - Request validation failed
- 500: Internal Server Error - Failed to list tasks
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task \
-H "Authorization: Bearer "
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task \
-H "Authorization: Bearer " \
-d name=string \
-d tag_id=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task \
-H "Authorization: Bearer " \
-d name=string \
-d tag_id=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task \
-H "Authorization: Bearer " \
-d name=string \
-d tag_id=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task \
-H "Authorization: Bearer " \
-d name=string \
-d tag_id=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task \
-H "Authorization: Bearer " \
-d name=string \
-d tag_id=string
```
# Create a New Task
```http
POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task
Content-Type: application/json
```
Create a new Task with specified prompts, model configuration, and output format.
Tasks are the core building blocks that define how the LLM processes inputs and generates structured outputs. Each Task includes:
- System and user prompts that guide the LLM's behavior
- Input parameters that can be dynamically provided when running the Task
- Output format specification that ensures consistent, structured responses
- Optional image processing capabilities
- Optional RAG (Retrieval Augmented Generation) for domain-specific knowledge
The Task will be created with an initial revision that becomes automatically active.
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Response Body
- 200: Successful Response
- 400: Bad Request - Invalid task configuration
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions or invalid resource access
- 422: Unprocessable Entity - Request validation failed
- 500: Internal Server Error - Failed to create task
## Examples
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"system_prompt": "You are an expert software program specifically designed for the fintech industry that will be used for pre-triage tasks to ensure the best possible client UX and efficient 3rd party platform interoperability.",
"user_prompt": "Your task is to validate the uploaded image and determine whether it will be suitable for authentication and onboarding checks. If the image of the person is clear and typical of a passport style photo then set the compliance field to true. Provide rationale for your decision in the rationale field. If the compliance result is false, then provide a helpful hint for the customer who has submitted the photo informing them why it is unacceptable and some steps to remedy it, place this into the hint field. Determine whether the following description matches the provided image: {description}",
"llm_model_id": "019011e6-e530-3aca-6cf7-2973387c255d",
"output_format": {
"compliance": "bool",
"hint": {
"type": "str"
},
"match": {
"type": "bool",
"description": "True if the provided description is a close match"
},
"rationale": "str"
},
"name": "Fintech Pre-Triage",
"enabled": true,
"llm_config": {
"temperature": 0.7
},
"task_forwarder_id": "0190a234-8dc6-6d08-aea9-928fcecad8f1",
"rag": {
"collection_id": "0190a234-8dc6-6d08-aea9-928fcecad8f1",
"rag_param": "context"
},
"image_required": true,
"optimise_images": true,
"test": false,
"input_processors": [
{
"param_name": "description",
"input_processor": "url_scraper",
"config": {
"extract_text": true,
"include_title": true,
"max_length": 5000
}
}
],
"annotation": "Production v2 - Added image matching capability",
"description": "A task to pre-triage user onboarding before IDV."
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"system_prompt": "string",
"user_prompt": "string",
"llm_model_id": "string",
"output_format": {
"string": {
"type": "str"
}
},
"name": "string",
"enabled": true
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"system_prompt": "string",
"user_prompt": "string",
"llm_model_id": "string",
"output_format": {
"string": {
"type": "str"
}
},
"name": "string",
"enabled": true
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"system_prompt": "string",
"user_prompt": "string",
"llm_model_id": "string",
"output_format": {
"string": {
"type": "str"
}
},
"name": "string",
"enabled": true
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"system_prompt": "string",
"user_prompt": "string",
"llm_model_id": "string",
"output_format": {
"string": {
"type": "str"
}
},
"name": "string",
"enabled": true
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"system_prompt": "string",
"user_prompt": "string",
"llm_model_id": "string",
"output_format": {
"string": {
"type": "str"
}
},
"name": "string",
"enabled": true
}'
```
# Get Task Details
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}
```
Retrieve detailed information about a specific Task.
Returns the complete Task configuration including:
- Basic properties (name, description, enabled status)
- All revisions with their prompts and configurations
- Currently active revisions and their traffic weights
- Associated tags and metadata
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- TaskId (required): The specific Task to reference.
## Query Parameters
- RevisionTagId (optional): Filter task_revisions by tag ID.
- IncludeTests (optional): Include test revisions
## Response Body
- 200: Successful Response
- 400: Bad Request - Invalid task ID format
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to access the task
- 404: Not Found - Task does not exist
- 422: Unprocessable Entity - Request validation failed
- 500: Internal Server Error - Failed to retrieve task
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/01909843-3596-da54-4756-28af46917e74 \
-H "Authorization: Bearer "
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-d revision_tag_id=string \
-d include_tests=true
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-d revision_tag_id=string \
-d include_tests=true
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-d revision_tag_id=string \
-d include_tests=true
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-d revision_tag_id=string \
-d include_tests=true
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-d revision_tag_id=string \
-d include_tests=true
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-d revision_tag_id=string \
-d include_tests=true
```
# Update a Task
```http
POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}
Content-Type: application/json
```
Update an existing Task with new configuration or create a new revision.
When updating a Task, you can:
1. Modify basic Task properties (name, description, enabled status)
2. Create a new revision with updated prompts and configuration
3. Manage active revisions and their traffic weights
4. Update tags for the Task or specific revisions
Note: Creating a new revision does not automatically make it active. Use the active_revisions field to control which revisions receive traffic.
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- TaskId (required): The specific Task to reference.
## Response Body
- 200: Successful Response
- 400: Bad Request - Invalid task configuration
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions or invalid resource access
- 404: Not Found - Task or referenced resource not found
- 422: Unprocessable Entity - Request validation failed
- 500: Internal Server Error - Failed to update task
## Examples
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/01909843-3596-da54-4756-28af46917e74 \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
# Delete Task
```http
DELETE https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}
```
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- TaskId (required): The specific Task to reference.
## Response Body
- 200: Successful Response
- 400: Bad Request
- 403: Forbidden
- 422: Validation Error
## Examples
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/01909843-3596-da54-4756-28af46917e74 \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id \
-H "Authorization: Bearer "
```
# Fetch Token Report
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/token_report
```
Retrieve detailed token usage statistics for a specific task.
This endpoint provides comprehensive token consumption data, including:
- Total tokens used across all task runs
- Token usage breakdown by time period
- Average tokens per request
- Usage patterns and trends
Parameters:
- start_date: Filter data from this date onward (supports both absolute dates and relative times)
- end_date: Filter data up to this date (supports both absolute dates and relative times)
Date Format Options:
1. Absolute dates: 'YYYY-MM-DD' (e.g., '2024-01-15')
2. Relative times:
- 'now', 'today', 'yesterday'
- 'X hours/days/weeks ago' (e.g., '24 hours ago', '7 days ago')
- 'last week', 'last month'
Common Use Cases:
1. Monitoring token consumption trends
2. Cost analysis and budgeting
3. Usage pattern analysis
4. Resource allocation planning
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- TaskId (required): The specific Task to reference.
## Query Parameters
- StartDate (optional): Start date for the report (e.g., '2023-06-01', '24 hours ago', 'yesterday').
- EndDate (optional): End date for the report (e.g., '2023-06-30', 'now', 'today').
## Response Body
- 200: Successfully retrieved token usage report
- 400: Bad Request - Invalid date format or range
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to access token usage data
- 404: Not Found - Task does not exist
- 422: Unprocessable Entity - Request validation failed
- 500: Internal Server Error - Failed to retrieve token usage data
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/01909843-3596-da54-4756-28af46917e74/token_report \
-H "Authorization: Bearer "
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/token_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/token_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/token_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/token_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/token_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/token_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
# Fetch Usage Report
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/usage_report
```
Retrieve usage statistics for task executions.
This endpoint provides detailed usage data about task runs, including:
- Number of executions over time
- Success and failure rates
- Usage patterns by time period
- Aggregated metrics by day or week
Use this data to:
1. Monitor task usage patterns
2. Track execution success rates
3. Analyze usage trends
4. Plan capacity and scaling
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- TaskId (required): The specific Task to reference.
## Query Parameters
- Aggregation (optional): The aggregation level for the report. Can be either 'day' or 'week'.
## Response Body
- 200: Successful Response
- 400: Bad Request - Invalid aggregation parameter (must be 'week' or 'day')
- 401: Unauthorized - Missing or invalid authentication token
- 403: Forbidden - User lacks required permissions to access task usage data
- 404: Not Found - The specified task ID does not exist
- 422: Unprocessable Entity - Request validation failed
- 500: Internal Server Error - Failed to process usage data due to server-side error
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/01909843-3596-da54-4756-28af46917e74/usage_report \
-H "Authorization: Bearer "
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/usage_report \
-H "Authorization: Bearer " \
-d aggregation=week
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/usage_report \
-H "Authorization: Bearer " \
-d aggregation=week
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/usage_report \
-H "Authorization: Bearer " \
-d aggregation=week
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/usage_report \
-H "Authorization: Bearer " \
-d aggregation=week
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/usage_report \
-H "Authorization: Bearer " \
-d aggregation=week
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/usage_report \
-H "Authorization: Bearer " \
-d aggregation=week
```
# Fetch Credit Report
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/credit_report
```
Retrieve detailed credit usage statistics for a specific task.
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- TaskId (required): The specific Task to reference.
## Query Parameters
- StartDate (optional): Start date for the report (e.g., '2023-06-01', '24 hours ago', 'yesterday').
- EndDate (optional): End date for the report (e.g., '2023-06-30', 'now', 'today').
## Response Body
- 200: Successful Response
- 400: Bad Request - Invalid date format or range, or unsupported aggregation level
- 401: Unauthorized - Missing or invalid authentication token
- 403: Forbidden - User lacks required permissions to access task timing data
- 404: Not Found - The specified task ID does not exist
- 422: Unprocessable Entity - Request validation failed
- 500: Internal Server Error - Failed to process timing data due to server-side error
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/01909843-3596-da54-4756-28af46917e74/credit_report \
-H "Authorization: Bearer "
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/credit_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/credit_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/credit_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/credit_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/credit_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/credit_report \
-H "Authorization: Bearer " \
-d start_date=string \
-d end_date=string
```
# List Task Runs
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run
```
Retrieve a paginated list of task runs for a specific task.
Task runs provide an audit trail of all task executions, including:
- Input parameters used
- Execution status and timing
- Resource usage metrics
- Output results
- Error information for failed runs
This endpoint supports:
- Pagination using cursor-based navigation
- Filtering by task revision
- Sorting by creation time (newest first)
Common use cases:
1. Monitoring task execution history
2. Auditing task usage and performance
3. Debugging task behavior across multiple runs
4. Analyzing task output patterns
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- TaskId (required): The specific Task to reference.
## Query Parameters
- PageLimit (optional): The maximum number of items to return per page. Defaults to `100` if not specified.
- Cursor (optional): A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results.
- Status (optional)
- TaskRevisionId (optional): Filter task runs by revision ID
## Response Body
- 200: Successfully retrieved task runs
- 400: Bad Request - Invalid parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to list task runs
- 404: Not Found - Task or revision not found
- 422: Unprocessable Entity - Request body validation failed
- 500: Internal Server Error - Failed to retrieve task runs
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/01909843-3596-da54-4756-28af46917e74/run \
-H "Authorization: Bearer "
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
# Run Task
```http
POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run
```
Run a task with the specified inputs and receive structured output.
This endpoint executes the task using its active revision(s) and returns the results. Key features:
1. Automatic revision selection based on traffic weights
2. Structured output matching the task's output_format
3. Execution metadata (tokens, timing, etc.)
4. Support for file uploads when required
Required:
- Input parameters as defined in the task's user_prompt
- Image file if task has image_required=true
Optional:
- Specific revision_id for testing or comparison
- Custom execution parameters
The response includes:
- Structured output matching the task's output_format
- Execution metadata (tokens used, timing)
- Input data for audit purposes
- References to any processed images
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- TaskId (required): The specific Task to reference.
## Query Parameters
- RevisionId (optional): Optional Task Revision ID to use for execution. If not provided, an active revision will be selected based on traffic weights.
## Response Body
- 200: Successful Response
- 400: Bad Request - Invalid task input format or missing required file
- 401: Unauthorized - Missing or invalid authentication token
- 403: Forbidden - User lacks required permissions or task is disabled
- 404: Not Found - The specified task or revision ID does not exist
- 422: Unprocessable Entity - Invalid task input parameters or revision ID format
- 500: Internal Server Error - Task execution failed due to server-side error
## Examples
```shell
curl -X POST "https://app.rightbrain.ai/api/v1/org/org_id/project/project_id/task/task_id/run?revision_id=0190a234-8dc6-6d08-aea9-928fcecad8f1" \
-H "Authorization: Bearer "
```
```shell
curl -X POST "https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run?revision_id=string" \
-H "Authorization: Bearer "
```
```shell
curl -X POST "https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run?revision_id=string" \
-H "Authorization: Bearer "
```
```shell
curl -X POST "https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run?revision_id=string" \
-H "Authorization: Bearer "
```
```shell
curl -X POST "https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run?revision_id=string" \
-H "Authorization: Bearer "
```
```shell
curl -X POST "https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run?revision_id=string" \
-H "Authorization: Bearer "
```
```shell
curl -X POST "https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run?revision_id=string" \
-H "Authorization: Bearer "
```
# Fetch a Task Run
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run/{task_run_id}
```
Retrieve detailed information about a specific task run.
Task runs provide a complete record of task executions, including:
- Input parameters and configuration used
- Execution status and timing information
- Resource usage metrics (e.g., tokens consumed)
- Structured output and processing metadata
- Error information if the run failed
This endpoint is useful for:
- Monitoring task execution progress
- Debugging failed runs
- Auditing task usage and performance
- Retrieving task results
Errors:
- Returns 400 if the task run ID is not a valid UUID format
- Returns 422 if the request body fails validation
- Returns 404 if the task run is not found
- Returns 403 if the user lacks permission to access the task run
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
- TaskId (required): The specific Task to reference.
- TaskRunId (required): The specific Task Run to reference.
## Response Body
- 200: Successfully retrieved task run information
- 401: Unauthorized - Authentication failed or token is invalid
- 404: Not Found - Task run does not exist
- 500: Internal Server Error - Failed to retrieve task run
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task/01909843-3596-da54-4756-28af46917e74/run/129c78d7-2e1f-4a77-adf3-68d69b0a3c71 \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run/:task_run_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run/:task_run_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run/:task_run_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run/:task_run_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run/:task_run_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task/:task_id/run/:task_run_id \
-H "Authorization: Bearer "
```
# List all Task Forwarders
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task_forwarder
```
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Query Parameters
- PageLimit (optional): The maximum number of items to return per page. Defaults to `100` if not specified.
- Cursor (optional): A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results.
## Response Body
- 200: Successfully retrieved task forwarders
- 400: Bad Request - Invalid parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to list task forwarders
- 404: Not Found - Project not found
- 422: Unprocessable Entity - Query parameter validation failed
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task_forwarder \
-H "Authorization: Bearer "
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
# Create a Task Forwarder
```http
POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task_forwarder
Content-Type: application/json
```
A Task Forwarder will receive the output of a Task and forward it to the specified destination. This can be used to send data to external systems, or to trigger other actions based on the output of a Task.
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Response Body
- 200: Successfully created task forwarder
- 400: Bad Request - Invalid path parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to create task forwarder
- 404: Not Found - Project not found
- 422: Unprocessable Entity - Task forwarder validation failed
## Examples
```shell Successful Task Forwarder Creation
curl -X POST https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task_forwarder \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "Webhook Endpoint",
"description": "Send all Task output to this API endpoint to ensure real-time updates of all Task Runs.",
"config": {
"destination_url": "https://eoalydnvgieppd9.m.pipedream.net"
},
"config_sensitive": {
"signing_key": "sdkjhsfd2sdfkj3223.23rh"
}
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'
```
# Fetch a Task Forwarder
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task_forwarder/{task_forwarder_id}
```
## Path Parameters
- TaskForwarderId (required): The specific Task to reference.
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Response Body
- 200: Successfully retrieved task forwarder
- 400: Bad Request - Invalid path parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to view task forwarder
- 404: Not Found - Task forwarder not found
- 422: Unprocessable Entity - Path parameter validation failed
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task_forwarder/01909843-3596-da54-4756-28af46917e74 \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder/:task_forwarder_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder/:task_forwarder_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder/:task_forwarder_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder/:task_forwarder_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder/:task_forwarder_id \
-H "Authorization: Bearer "
```
# Update a Task Forwarder
```http
POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task_forwarder/{task_forwarder_id}
Content-Type: application/json
```
## Path Parameters
- TaskForwarderId (required): The specific Task to reference.
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Response Body
- 200: Successfully updated task forwarder
- 400: Bad Request - Invalid path parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to update task forwarder
- 404: Not Found - Task forwarder not found
- 422: Unprocessable Entity - Task forwarder update validation failed
## Examples
```shell Successfully Updated Task Forwarder
curl -X POST https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/task_forwarder/01909843-3596-da54-4756-28af46917e74 \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder/:task_forwarder_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder/:task_forwarder_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder/:task_forwarder_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder/:task_forwarder_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/task_forwarder/:task_forwarder_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
# List Available LLM Models
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/model
```
Retrieve a list of all available Large Language Models (LLMs) that can be used in Tasks.
Each model entry includes:
- Unique identifier
- Provider information (e.g., OpenAI, Anthropic)
- Model reference name for API calls
- Human-readable alias
- Detailed description of capabilities
- Vision support status
Models may have different:
- Context window sizes
- Knowledge cutoff dates
- Capabilities (e.g., vision support)
- Cost structures
- Performance characteristics
Choose models based on your specific needs:
- GPT-4 models for complex reasoning
- Vision-enabled models for image analysis
- Models with larger context windows for processing longer documents
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Response Body
- 200: Successfully retrieved list of available LLM models
- 400: Bad Request - Invalid UUID format in path parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to list models
- 404: Not Found - Project not found
- 422: Unprocessable Entity - Path parameter validation failed
- 500: Internal Server Error - Failed to retrieve models
## Examples
```shell Available LLM Models
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/model \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/model \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/model \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/model \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/model \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/model \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/model \
-H "Authorization: Bearer "
```
# List available Input Processors
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/input_processor
```
Returns a list of all available input processors that can be used to transform task inputs.
Input processors are utility functions that can modify or enhance the input data before it is processed by the task.
For example, the url_fetcher processor can fetch HTML content from a URL and replace the URL with the actual content.
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Response Body
- 200: Successfully retrieved list of available input processors
- 400: Bad Request - Invalid UUID format in path parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to list input processors
- 404: Not Found - Project not found
- 422: Unprocessable Entity - Path parameter validation failed
- 500: Internal Server Error - Failed to retrieve input processors
## Examples
```shell Available Input Processors
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/input_processor \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/input_processor \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/input_processor \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/input_processor \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/input_processor \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/input_processor \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/input_processor \
-H "Authorization: Bearer "
```
# Get OAuth Client Details
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/oauth_client/{oauth_client_id}
```
Retrieve detailed information about a specific OAuth client.
Returns the complete client configuration including:
- Client credentials (ID and secret)
- Authorized redirect URIs
- Supported grant types
- Creation and modification timestamps
Use this endpoint to:
- Verify client configuration
- Check authorized redirect URIs
- Review supported grant types
- Audit client creation/modification times
## Path Parameters
- OauthClientId (required): The unique identifier of the OAuth client to retrieve. This is the internal UUID, not the OAuth 2.0 client_id used for authentication.
- OrgId (required): The unique identifier of the organization that owns the project containing this OAuth client.
- ProjectId (required): The unique identifier of the project that contains this OAuth client. OAuth clients are scoped to projects for access control.
## Response Body
- 200: Successfully retrieved OAuth client details
- 400: Bad Request - Invalid path parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to view OAuth client
- 404: Not Found - OAuth client not found
- 422: Unprocessable Entity - Path parameter validation failed
## Examples
```shell Successfully Retrieved OAuth Client
curl https://app.rightbrain.ai/api/v1/org/0190a234-8dc6-6d08-aea9-928fcecad8f2/project/0190a234-8dc6-6d08-aea9-928fcecad8f3/oauth_client/0190a234-8dc6-6d08-aea9-928fcecad8f1 \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer "
```
```shell
curl https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer "
```
# Update OAuth Client
```http
POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/oauth_client/{oauth_client_id}
Content-Type: application/json
```
Update an existing OAuth client's configuration.
Modifiable settings:
- Authorized redirect URIs
- Supported grant types
Notes:
- Client ID and secret cannot be changed
- Client type (user/project) cannot be modified
- Updates are atomic - all changes succeed or none do
- Previous configuration remains valid until update succeeds
Use this endpoint to:
- Add/remove redirect URIs
- Modify supported grant types
- Update client configuration without disrupting existing tokens
## Path Parameters
- OauthClientId (required)
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Response Body
- 200: OAuth client updated successfully
- 400: Bad Request - Invalid path parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to update OAuth client
- 404: Not Found - OAuth client not found
- 422: Unprocessable Entity - OAuth client update validation failed
## Examples
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/oauth_client/oauth_client_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
# Delete Oauth Client
```http
DELETE https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/oauth_client/{oauth_client_id}
```
## Path Parameters
- OauthClientId (required)
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Response Body
- 200: Successful Response
- 400: Bad Request
- 403: Forbidden
- 422: Validation Error
## Examples
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/oauth_client/oauth_client_id \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id \
-H "Authorization: Bearer "
```
# List OAuth Clients
```http
GET https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/oauth_client
```
Retrieve a paginated list of all OAuth clients in the project.
OAuth clients enable secure API access through different grant types:
Grant Types:
1. Client Credentials
- For server-to-server API access
- No user interaction required
- No redirect URIs needed
- Returns access token directly
- Best for automated processes and service accounts
2. Authorization Code
- For user-based access to the API
- Requires redirect URIs for OAuth flow
- Most secure for web applications
- Flow:
1. User is redirected to authorization server
2. After consent, redirects back to your app with auth code
3. Your app exchanges code for tokens
- Required for web applications accessing user data
3. Refresh Token
- Enables long-term API access
- Used with authorization code flow
- Allows getting new access tokens without user interaction
- No redirect URIs needed for refresh flow itself
- Best for maintaining persistent access
4. Implicit (Legacy)
- For browser-based applications
- Requires redirect URIs
- Returns token in URL fragment
- Less secure than authorization code
- Not recommended for new applications
Redirect URIs:
- Required for authorization code and implicit flows
- Must be exact match when used
- Common formats:
- Web apps: https://app.example.com/oauth/callback
- Local development: http://localhost:3000/callback
- Mobile apps: myapp://oauth/callback
- Security requirements:
- Must use HTTPS in production
- Cannot contain fragments (#)
- Should be specific paths, not generic domains
- Maximum length: 2048 characters
Each client in the list includes:
- Unique client ID
- Name and description
- Configured redirect URIs
- Supported grant types
- Creation and modification timestamps
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Query Parameters
- PageLimit (optional): The maximum number of items to return per page. Defaults to `100` if not specified.
- Cursor (optional): A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results.
## Response Body
- 200: Successfully retrieved list of OAuth clients
- 400: Bad Request - Invalid query parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to list OAuth clients
- 404: Not Found - Project not found
- 422: Unprocessable Entity - Path parameter validation failed
## Examples
```shell
curl https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/oauth_client \
-H "Authorization: Bearer "
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
```shell
curl -G https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client \
-H "Authorization: Bearer " \
-d page_limit=0 \
-d cursor=string
```
# Create OAuth Client
```http
POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/oauth_client
Content-Type: application/json
```
Create a new OAuth client for API access.
Configure the client with:
- Name and description
- Authorized redirect URIs for OAuth flows
- Supported grant types
- Client type (user or project)
Grant Types:
1. Client Credentials
- For server-to-server API access
- No user interaction required
- No redirect URIs needed
- Returns access token directly
- Best for automated processes and service accounts
2. Authorization Code
- For user-based access to the API
- Requires redirect URIs for OAuth flow
- Most secure for web applications
- Flow:
1. User is redirected to authorization server
2. After consent, redirects back to your app with auth code
3. Your app exchanges code for tokens
- Required for web applications accessing user data
3. Refresh Token
- Enables long-term API access
- Used with authorization code flow
- Allows getting new access tokens without user interaction
- No redirect URIs needed for refresh flow itself
- Best for maintaining persistent access
4. Implicit (Legacy)
- For browser-based applications
- Requires redirect URIs
- Returns token in URL fragment
- Less secure than authorization code
- Not recommended for new applications
Redirect URIs:
- Required for authorization code and implicit flows
- Must be exact match when used
- Common formats:
- Web apps: https://app.example.com/oauth/callback
- Local development: http://localhost:3000/callback
- Mobile apps: myapp://oauth/callback
- Security requirements:
- Must use HTTPS in production
- Cannot contain fragments (#)
- Should be specific paths, not generic domains
- Maximum length: 2048 characters
Client types:
- User: Standard OAuth client tied to the creating user's permissions
- Project: Service account OAuth client with project-level permissions
The response includes:
- Client ID and secret (shown only once)
- Configured redirect URIs
- Supported grant types
- Creation timestamp
Security note: Store the client secret securely as it cannot be retrieved later.
## Path Parameters
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Response Body
- 200: Successful Response
- 400: Bad Request - Invalid path parameters
- 401: Unauthorized - Authentication failed or token is invalid
- 403: Forbidden - Insufficient permissions to create OAuth client
- 404: Not Found - Project not found
- 422: Unprocessable Entity - OAuth client validation failed
## Examples
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/oauth_client \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "Production API Client"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'
```
# Regenerate Oauth Client Secret
```http
POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/oauth_client/{oauth_client_id}/client_secret
Content-Type: application/json
```
## Path Parameters
- OauthClientId (required)
- OrgId (required): The unique identifier of the organization.
- ProjectId (required): The unique identifier of the project.
## Response Body
- 200: Successful Response
- 400: Bad Request
- 403: Forbidden
- 422: Validation Error
## Examples
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/123e4567-e89b-12d3-a456-426614174000/project/123e4567-e89b-12d3-a456-426614174001/oauth_client/oauth_client_id/client_secret \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id/client_secret \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id/client_secret \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```shell
curl -X POST https://app.rightbrain.ai/api/v1/org/:org_id/project/:project_id/oauth_client/:oauth_client_id/client_secret \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```