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

# API Overview

## Accessing the API

All API endpoints are available at `https://api.thesys.dev/v1`.

## Authentication

Authentication is done via API keys. You can create API keys from the [keys page](https://console.thesys.dev/keys).
API keys must be sent as a `Authorization` header with the value `Bearer <api_key>`.
If the API key is not valid, you will receive a 403 error.

## Rate Limits

Please refer to the [Rate Limits](/api-reference/rate-limits) page for more information.

## Errors

Please refer to the [Errors](/api-reference/errors) page for more information.

## Examples

### For Chat Completions API

<CodeGroup>
  ```python python theme={null}
  from openai import OpenAI
  client = OpenAI(
      base_url="https://api.thesys.dev/v1/embed",
      api_key="<api_key>"
  )

  completion = client.chat.completions.create(
  model="c1/anthropic/claude-sonnet-4/v-20250930",
  messages=[
  {
  "role": "user",
  "content": "How did the population of the world grow from 1950 to 2020?"
  }
  ])

  ```

  ```js node theme={null}
  import OpenAI from "openai";
  const client = new OpenAI({
      base_url="https://api.thesys.dev/v1/embed",
      api_key="<api_key>"
  });

  const completion = await client.chat.completions.create({
      model: "c1/anthropic/claude-sonnet-4/v-20250930",
      messages: [
          {
              role: "user",
              content: "How did the population of the world grow from 1950 to 2020?",
          },
      ],
  });
  ```
</CodeGroup>

<Note>
  Stream this response via the language specific helper functions to the react
  client.
</Note>

### For Responses API

<CodeGroup>
  ```python python theme={null}
  from openai import OpenAI
  client = OpenAI(
      base_url="https://api.thesys.dev/v1/embed",
      api_key="<api_key>"
  )

  response = client.responses.create(
  model="c1/anthropic/claude-sonnet-4/v-20250930",
  input="How did the population of the world grow from 1950 to 2020?"
  )

  print(response)

  ```

  ```js node theme={null}
  import OpenAI from "openai";
  const client = new OpenAI({
      baseURL: "https://api.thesys.dev/v1/embed",
      apiKey: "<api_key>"
  });

  const response = await client.responses.create({
      model: "c1/anthropic/claude-sonnet-4/v-20250930",
      input: "How did the population of the world grow from 1950 to 2020?",
  });

  console.log(response);
  ```
</CodeGroup>

## Chat Completions API

<Info>
  For C1 Gemini models, the `reasoning_effort` parameter translates to the following max reasoning tokens:

  | `reasoning_effort` | 3 Flash - Max reasoning tks | 3 Pro - Max reasoning tks |
  | ------------------ | --------------------------- | ------------------------- |
  | `none`             | 0                           | 256                       |
  | `minimal`          | 512                         | 512                       |
  | `low`              | 1024                        | 1024                      |
  | `medium`           | 2048                        | 2048                      |
  | `high`             | 4096                        | 4096                      |
  | `xhigh`            | 8192                        | 8192                      |
</Info>

| Property                | C1 OpenAI models                                          | C1 Anthropic Models                                       |
| ----------------------- | --------------------------------------------------------- | --------------------------------------------------------- |
| `messages`              | <Icon icon="check" color="green" /> (audio not supported) | <Icon icon="check" color="green" /> (audio not supported) |
| `model`                 | <Icon icon="check" color="green" />                       | <Icon icon="check" color="green" />                       |
| `audio`                 | <Icon icon="minus" color="lightgray" size="16" />         | <Icon icon="minus" color="lightgray" size="16" />         |
| `frequency_penalty`     | <Icon icon="minus" color="lightgray" size="16" />         | <Icon icon="minus" color="lightgray" size="16" />         |
| `function_call`         | use `tool_choice`                                         | use `tool_choice`                                         |
| `functions`             | use `tools`                                               | use `tools`                                               |
| `logit_bias`            | <Icon icon="minus" color="lightgray" size="16" />         | <Icon icon="minus" color="lightgray" size="16" />         |
| `logprobs`              | <Icon icon="minus" color="lightgray" size="16" />         | <Icon icon="minus" color="lightgray" size="16" />         |
| `max_completion_tokens` | <Icon icon="check" color="green" />                       | <Icon icon="check" color="green" />                       |
| `max_tokens`            | <Icon icon="check" color="green" />                       | <Icon icon="check" color="green" />                       |
| `metadata`              | `thesys` metadata only                                    | `thesys` metadata only                                    |
| `modalities`            | <Icon icon="minus" color="lightgray" size="16" />         | <Icon icon="minus" color="lightgray" size="16" />         |
| `n`                     | must be `1`                                               | must be `1`                                               |
| `parallel_tool_calls`   | <Icon icon="check" color="green" /> `true` by default     | <Icon icon="check" color="green" /> `true` by default     |
| `prediction`            | <Icon icon="minus" color="lightgray" size="16" />         | <Icon icon="minus" color="lightgray" size="16" />         |
| `presence_penalty`      | <Icon icon="minus" color="lightgray" size="16" />         | <Icon icon="minus" color="lightgray" size="16" />         |
| `prompt_cache_key`      | <Icon icon="check" color="green" />                       | <Icon icon="minus" color="lightgray" size="16" />         |
| `reasoning_effort`      | <Icon icon="check" color="green" />                       | <Icon icon="minus" color="lightgray" size="16" />         |
| `response_format`       | <Icon icon="minus" color="lightgray" size="16" />         | <Icon icon="minus" color="lightgray" size="16" />         |
| `service_tier`          | <Icon icon="minus" color="lightgray" size="16" />         | <Icon icon="minus" color="lightgray" size="16" />         |
| `stop`                  | <Icon icon="check" color="green" />                       | <Icon icon="check" color="green" />                       |
| `stream`                | <Icon icon="check" color="green" />                       | <Icon icon="check" color="green" />                       |
| `temperature`           | <Icon icon="check" color="green" />                       | <Icon icon="check" color="green" />                       |
| `tool_choice`           | <Icon icon="check" color="green" />                       | <Icon icon="check" color="green" />                       |
| `tools`                 | <Icon icon="check" color="green" />                       | <Icon icon="check" color="green" />                       |
| `top_p`                 | <Icon icon="check" color="green" />                       | <Icon icon="check" color="green" />                       |
| `verbosity`             | <Icon icon="check" color="green" />                       | <Icon icon="minus" color="lightgray" size="16" />         |
| `web_search_options`    | <Icon icon="minus" color="lightgray" size="16" />         | <Icon icon="minus" color="lightgray" size="16" />         |

## Responses API

<Tip>
  All C1 models are supported via the Responses API, including OpenAI and
  non-OpenAI models. Our Responses API implementation is [Open
  Responses](https://www.openresponses.org/) compliant.
</Tip>

There are three ways to maintain chat history in Responses API:

1. **Pass the full conversation history** — Include all previous messages in the `input` array with each request.
2. **Use `previous_response_id`** — Reference a prior response by its ID to automatically chain conversations (requires `store: true`).
3. **Use `conversation`** — Group related responses into a named conversation for persistent multi-turn context (requires `store: true`).

To create a conversation using `previous_response_id`:

<CodeGroup>
  ```python python theme={null}
  from openai import OpenAI
  client = OpenAI(
      base_url="https://api.thesys.dev/v1/embed",
      api_key="<api_key>"
  )

  response = client.responses.create(
  model="c1/anthropic/claude-sonnet-4/v-20250930",
  input="What is the capital of France?"
  )

  follow_up = client.responses.create(
  model="c1/anthropic/claude-sonnet-4/v-20250930",
  input="And what is its population?",
  previous_response_id=response.id
  )

  print(follow_up)

  ```

  ```js node theme={null}
  import OpenAI from "openai";
  const client = new OpenAI({
      baseURL: "https://api.thesys.dev/v1/embed",
      apiKey: "<api_key>"
  });

  const response = await client.responses.create({
      model: "c1/anthropic/claude-sonnet-4/v-20250930",
      input: "What is the capital of France?",
  });

  const followUp = await client.responses.create({
      model: "c1/anthropic/claude-sonnet-4/v-20250930",
      input: "And what is its population?",
      previous_response_id: response.id,
  });

  console.log(followUp);
  ```
</CodeGroup>

To create a conversation and use it across multiple requests:

<CodeGroup>
  ```python python theme={null}
  from openai import OpenAI

  # Client for conversation management

  conv_client = OpenAI(
  base_url="https://api.thesys.dev",
  api_key="<api_key>"
  )

  # Client for generation

  embed_client = OpenAI(
  base_url="https://api.thesys.dev/v1/embed",
  api_key="<api_key>"
  )

  conversation = conv_client.conversations.create()

  response = embed_client.responses.create(
  model="c1/anthropic/claude-sonnet-4/v-20250930",
  input="What is the capital of France?",
  store=True,
  conversation={"id": conversation.id}
  )

  follow_up = embed_client.responses.create(
  model="c1/anthropic/claude-sonnet-4/v-20250930",
  input="And what is its population?",
  store=True,
  conversation={"id": conversation.id}
  )

  print(follow_up)

  ```

  ```js node theme={null}
  import OpenAI from "openai";

  // Client for conversation management
  const convClient = new OpenAI({
      baseURL: "https://api.thesys.dev",
      apiKey: "<api_key>"
  });

  // Client for generation
  const embedClient = new OpenAI({
      baseURL: "https://api.thesys.dev/v1/embed",
      apiKey: "<api_key>"
  });

  const conversation = await convClient.conversations.create();

  const response = await embedClient.responses.create({
      model: "c1/anthropic/claude-sonnet-4/v-20250930",
      input: "What is the capital of France?",
      store: true,
      conversation: { id: conversation.id },
  });

  const followUp = await embedClient.responses.create({
      model: "c1/anthropic/claude-sonnet-4/v-20250930",
      input: "And what is its population?",
      store: true,
      conversation: { id: conversation.id },
  });

  console.log(followUp);
  ```
</CodeGroup>

<Info>
  Built-in tools (`web_search`, `file_search`, `code_interpreter`,
  `computer_use`, `mcp`) will be supported soon.
</Info>

| Property                 | Supported                                                                       |
| ------------------------ | ------------------------------------------------------------------------------- |
| `background`             | <Icon icon="check" color="green" /> Always `false`                              |
| `conversation`           | <Icon icon="check" color="green" /> with `store: true`                          |
| `include`                | <Icon icon="minus" color="lightgray" size="16" />                               |
| `input`                  | <Icon icon="check" color="green" />                                             |
| `instructions`           | <Icon icon="check" color="green" />                                             |
| `max_output_tokens`      | <Icon icon="check" color="green" />                                             |
| `max_tool_calls`         | <Icon icon="check" color="green" />                                             |
| `metadata`               | <Icon icon="check" color="green" /> `thesys` metadata only                      |
| `model`                  | <Icon icon="check" color="green" />                                             |
| `parallel_tool_calls`    | <Icon icon="check" color="green" /> `true` by default                           |
| `previous_response_id`   | <Icon icon="check" color="green" /> with `store: true`                          |
| `prompt`                 | <Icon icon="minus" color="lightgray" size="16" />                               |
| `prompt_cache_key`       | <Icon icon="minus" color="lightgray" size="16" />                               |
| `prompt_cache_retention` | <Icon icon="minus" color="lightgray" size="16" />                               |
| `reasoning`              | <Icon icon="check" color="green" /> `effort` only                               |
| `safety_identifier`      | <Icon icon="minus" color="lightgray" size="16" />                               |
| `service_tier`           | <Icon icon="check" color="green" />                                             |
| `store`                  | <Icon icon="check" color="green" /> `true` by default                           |
| `stream`                 | <Icon icon="check" color="green" />                                             |
| `temperature`            | <Icon icon="check" color="green" />                                             |
| `text`                   | <Icon icon="check" color="green" /> `verbosity` only                            |
| `tool_choice`            | <Icon icon="check" color="green" />                                             |
| `tools`                  | <Icon icon="check" color="green" /> `function` only; built-in tools coming soon |
| `top_logprobs`           | <Icon icon="minus" color="lightgray" size="16" />                               |
| `top_p`                  | <Icon icon="minus" color="lightgray" size="16" />                               |

### `input` item types

| Input Item Type                                                                  | Supported                                                     |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `message` (user/system/developer/assistant)                                      | <Icon icon="check" color="green" />                           |
| `function_call`                                                                  | <Icon icon="check" color="green" />                           |
| `function_call_output`                                                           | <Icon icon="check" color="green" />                           |
| `item_reference`                                                                 | <Icon icon="minus" color="lightgray" size="16" />             |
| `reasoning`                                                                      | <Icon icon="minus" color="lightgray" size="16" />             |
| `compaction`                                                                     | <Icon icon="minus" color="lightgray" size="16" /> coming soon |
| `web_search_call`                                                                | <Icon icon="minus" color="lightgray" size="16" /> coming soon |
| `file_search_call`                                                               | <Icon icon="minus" color="lightgray" size="16" /> coming soon |
| `computer_call` / `computer_call_output`                                         | <Icon icon="minus" color="lightgray" size="16" /> coming soon |
| `code_interpreter_call`                                                          | <Icon icon="minus" color="lightgray" size="16" /> coming soon |
| `image_generation_call`                                                          | <Icon icon="minus" color="lightgray" size="16" /> coming soon |
| `local_shell_call` / `local_shell_call_output`                                   | <Icon icon="minus" color="lightgray" size="16" />             |
| `shell_call` / `shell_call_output`                                               | <Icon icon="minus" color="lightgray" size="16" />             |
| `apply_patch_call` / `apply_patch_call_output`                                   | <Icon icon="minus" color="lightgray" size="16" />             |
| `mcp_list_tools` / `mcp_approval_request` / `mcp_approval_response` / `mcp_call` | <Icon icon="minus" color="lightgray" size="16" /> coming soon |
| `custom_tool_call` / `custom_tool_call_output`                                   | <Icon icon="minus" color="lightgray" size="16" />             |

### `text` sub-fields

| Property         | Supported                                                              |
| ---------------- | ---------------------------------------------------------------------- |
| `text.verbosity` | <Icon icon="check" color="green" />                                    |
| `text.format`    | <Icon icon="minus" color="lightgray" size="16" /> Always Thesys format |