> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai21.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke assistant [Beta]

> Run Assistant by ID

## Path Parameters

<ParamField path="assistant_id" type="string" required>
  The unique identifier of the assistant to invoke.\
  Use `agent_id` when you want repeatable behavior without re-specifying name, instructions, tools, or the tool config each call.

  <Note>
    When you invoke an `assistant_id` and override a specific configuration (for example, updating only the `requirements`), the assistant uses your updated value for that field, while all other settings (such as `name`, `description`, and `budget`) are still taken from the `assistant_id`.
  </Note>
</ParamField>

## Request Body

<ParamField body="input" type="object[]" required>
  A list of message objects. Each object must include a `role` and `content`.

  <Accordion title="Show properties">
    <ParamField body="role" type="string" required>
      The role of the message sender.\
      Supported values: `assistant`, `user`.
    </ParamField>

    <ParamField body="content" type="string" required>
      The content of the message.
    </ParamField>
  </Accordion>
</ParamField>

<ParamField path="output_type" type="object">
  Reserved for specifying structured output format.
</ParamField>

<ParamField path="include" type="string[]">
  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 the `data_sources` field in the output.
  * `requirements_result` — Includes detailed results for each requirement in the `requirements_result` field.

      <RequestExample>
        ```python Python theme={"system"}
        import requests

        assistant_id = "your-assistant-id"
        api_key = "your-api-key"

        url = f"https://api.ai21.com/studio/v1/assistants/{assistant_id}"

        headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

        payload = {
            "input": [
                {
                    "role": "user",
                    "content": "string"
                }
            ],
            "output_type": "json",
            "include": [
                "data_sources",
                "requirements_result",
                "requirements_result.metadata"
            ]
        }

        response = requests.post(url, headers=headers, json=payload)

        print("Status Code:", response.status_code)
        print("Response:", response.json())
        ```

        ```javascript JavaScript theme={"system"}
        import fetch from "node-fetch";

        const assistantId = "your-assistant-id";
        const apiKey = "your-api-key";

        const url = `https://api.ai21.com/studio/v1/assistants/${assistantId}`;

        const payload = {
          input: [
            {
              role: "user",
              content: "string"
            }
          ],
          output_type: "json",
          include: [
            "data_sources",
            "requirements_result",
            "requirements_result.metadata"
          ]
        };

        const headers = {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        };

        async function runAssistant() {
          try {
            const response = await fetch(url, {
              method: "POST",
              headers,
              body: JSON.stringify(payload)
            });

            const data = await response.json();
            console.log("Status:", response.status);
            console.log("Response:", data);
          } catch (error) {
            console.error("Error:", error);
          }
        }

        runAssistant();
        ```

        ```php PHP theme={"system"}
        <?php
        $assistant_id = "your-assistant-id";
        $api_key = "your-api-key";

        $url = "https://api.ai21.com/studio/v1/assistants/" . $assistant_id;

        $payload = [
            "input" => [
                [
                    "role" => "user",
                    "content" => "string"
                ]
            ],
            "output_type" => "json",
            "include" => [
                "data_sources",
                "requirements_result",
                "requirements_result.metadata"
            ]
        ];

        $ch = curl_init($url);

        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            "Authorization: Bearer " . $api_key,
            "Content-Type: application/json"
        ]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

        $response = curl_exec($ch);

        if (curl_errno($ch)) {
            echo "Error: " . curl_error($ch);
        } else {
            $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
            echo "Status Code: " . $statusCode . "\n";
            echo "Response: " . $response . "\n";
        }

        curl_close($ch);
        ?>
        ```

        ```php Go theme={"system"}
        package main

        import (
        	"bytes"
        	"encoding/json"
        	"fmt"
        	"io"
        	"net/http"
        	"os"
        )

        func main() {
        	assistantID := "your-assistant-id"
        	apiKey := "your-api-key"

        	url := fmt.Sprintf("https://api.ai21.com/studio/v1/assistants/%s", assistantID)

        	payload := map[string]interface{}{
        		"input": []map[string]string{
        			{
        				"role":    "user",
        				"content": "string",
        			},
        		},
        		"output_type": "json",
        		"include":     []string{"data_sources", "requirements_result", "requirements_result.metadata"},
        	}

        	jsonData, err := json.Marshal(payload)
        	if err != nil {
        		fmt.Println("Error encoding JSON:", err)
        		os.Exit(1)
        	}

        	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
        	if err != nil {
        		fmt.Println("Error creating request:", err)
        		os.Exit(1)
        	}

        	req.Header.Set("Authorization", "Bearer "+apiKey)
        	req.Header.Set("Content-Type", "application/json")

        	client := &http.Client{}
        	resp, err := client.Do(req)
        	if err != nil {
        		fmt.Println("Error sending request:", err)
        		os.Exit(1)
        	}
        	defer resp.Body.Close()

        	body, err := io.ReadAll(resp.Body)
        	if err != nil {
        		fmt.Println("Error reading response:", err)
        		os.Exit(1)
        	}

        	fmt.Println("Status Code:", resp.StatusCode)
        	fmt.Println("Response:", string(body))
        }
        ```

        ```bash cURL theme={"system"}
        curl -X POST "https://api.ai21.com/studio/v1/assistants/your-assistant-id" \
          -H "Authorization: Bearer your-api-key" \
          -H "Content-Type: application/json" \
          -d '{
            "input": [
              {
                "role": "user",
                "content": "string"
              }
            ],
            "output_type": "json",
            "include": [
              "data_sources",
              "requirements_result",
              "requirements_result.metadata"
            ]
          }'
        ```

        ```java Java theme={"system"}
        import java.io.OutputStream;
        import java.io.InputStreamReader;
        import java.io.BufferedReader;
        import java.net.HttpURLConnection;
        import java.net.URL;

        public class InvokeAssistant {

            public static void main(String[] args) {
                String assistantId = "your-assistant-id";
                String apiKey = "your-api-key";
                String urlString = "https://api.ai21.com/studio/v1/assistants/" + assistantId;

                String jsonPayload = "{"
                        + "\"input\":[{\"role\":\"user\",\"content\":\"string\"}],"
                        + "\"output_type\":\"json\","
                        + "\"include\":[\"data_sources\",\"requirements_result\",\"requirements_result.metadata\"]"
                        + "}";

                try {
                    URL url = new URL(urlString);
                    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
                    conn.setRequestMethod("POST");
                    conn.setRequestProperty("Authorization", "Bearer " + apiKey);
                    conn.setRequestProperty("Content-Type", "application/json");
                    conn.setDoOutput(true);

                    // Send JSON payload
                    OutputStream os = conn.getOutputStream();
                    os.write(jsonPayload.getBytes("UTF-8"));
                    os.close();

                    // Read response
                    int status = conn.getResponseCode();
                    BufferedReader in = new BufferedReader(new InputStreamReader(
                            conn.getInputStream()));
                    String inputLine;
                    StringBuilder response = new StringBuilder();
                    while ((inputLine = in.readLine()) != null) {
                        response.append(inputLine);
                    }
                    in.close();

                    System.out.println("Status Code: " + status);
                    System.out.println("Response: " + response.toString());

                    conn.disconnect();

                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
        }
        ```

        ```json JSON theme={"system"}
        {
          "input": [
            {
              "role": "user",
              "content": "string"
            }
          ],
          "output_type": "json",
          "include": [
            "data_sources",
            "requirements_result",
            "requirements_result.metadata"
          ]
        }
        ```
      </RequestExample>
</ParamField>