API Reference
PlaygroundAPI KeyAccount
Start typing to search…

Create run

AI21 Maestro is currently in beta and available exclusively to early access users.

👍

Be among the first to try AI21 Maestro!

AI21 Maestro is currently in beta and available exclusively to early access users.

Join the waitlist for early access

Create run

POST https://api.ai21.com/studio/v1/maestro/runs

Execute a run based on the provided input.

Request body

input string | object[] Required

A list of conversational turns, alternating between the user and the assistant,
or a single instruction string.

Please note that there are two different options for the input.

show possible types

Text input string Optional
A plain instruction string for AI21 Maestro. Equivalent to a single message with the user role.

Input messages object[] Optional
A list of message objects representing a multi-turn conversation alternating between the user and the assistant.

show fields

role string Required
The role of the entity that is creating the message. Allowed values include:

user: A message is sent by an actual user. It represents the user’s intent.

assistant: A message is generated by the assistant.

content string Required
The textual content of the message.

requirements object[] Optional

Explicit requirements for the output. The requirements can be in terms of content, style, format, genre, point of view, and various guardrails AI21 Maestro will allocate resources to maintain all requirements throughout the run. At the end of the run, the score for each requirement and the overall score will be returned. Users can specify up to 10 requirements.

show fields

name string Required
The requirement's name, which allows users to reference it in their applications later.

description string Required
The requirement’s description in natural language.
This will influence our result scoring and budget allocation.
The maximum length for each description is 128 words.

is_mandatory boolean (Optional) Default: false If set to true, and the associated requirement is not fully satisfied, the overall requirements_result score will be 0.

Examples of requirements:

  • “Write up to 3 paragraphs”
  • “Output only the answer”
  • “Don’t mention a word about the company’s CEO”
  • “Use a friendly tone”

ℹ️

Avoid conflicting requirements

Conflicts may reduce run quality or prevent fulfillment.

models list of strings- defaults to None. Optional

Specify a single model to be used for the run. Choose from the following:

First-Party Models:

  • jamba-large-1.6
  • jamba-mini-1.6

Third-Party Models:

  • gpt-4.1-large
  • gpt-4.1-mini
  • gpt-4o
  • claude-3.5-sonnet
  • claude-3.7-sonnet
  • gemini-2.5-pro

budget string Optional
Controls how many resources AI21 Maestro allocates to fulfill the requirements. Accepted values:

  • high
  • medium
  • low

Defaults to low if not provided.

include string[] Optional

Specify which extra fields should be included in the output. If not provided, none of these fields will be included.
Supported values:

data_sources — Includes thedata_sources field in the output.

requirements_result — Includes detailed results for each requirement in the requirements_result field.

Returns

Run object

📘

Your Guide to Using AI21 Maestro

To better understand how to use these endpoints, see the AI21 Maestro guide.