# API reference

> Request fields, limits, and error codes for `POST /v1/chat/completions`.

The call is the OpenAI-compatible chat completion from the [quickstart](/docs/quickstart). This page is the fields, limits, and error codes on that request. Saving a skill and naming one are on the [skills](/docs/skills) page.

![Request fields, limits, and error codes on one plate](/docs/figures/api-reference.svg)

## Request fields

### reasoning_effort

How hard your fallback model reasons on the steps it writes. Omit it and the effort is `none`.

`reasoning_effort` is one of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`.

You can send the same choice as `reasoning`: `{ "effort": "low" }`. `reasoning.enabled` set to `true` means `medium`. Set to `false` it means `none`. If `reasoning_effort` and `reasoning.effort` are both set and they differ, the request is refused with `invalid_reasoning`.

The response reports the effort it used as `inferenceindex.reasoning_effort`, or `none` when the request asked for none.

### today

`today` is a date, `YYYY-MM-DD`. Steps that depend on the date use it. Omit it and the server's date is used.

### stream_options.include_usage

`stream: true` streams the completion. Tool calls still arrive whole. Set `stream_options` to `{ "include_usage": true }` to add a final chunk that carries `usage` and `inferenceindex`. Without it, `inferenceindex` is on the last content chunk and that stream has no usage chunk.

### Model

The model is `inferenceindex-0.1`. A saved skill is `inferenceindex-0.1/skl_` plus 32 hex characters, and `@` plus a version from 1 pins that version: `inferenceindex-0.1/skl_…@2`. The same id can be sent as `skill_id` and `skill_version` in the body, or as `X-Skill-Id` and `X-Skill-Version`. The [skills](/docs/skills) page has the rest. `GET /v1/models` lists `inferenceindex-0.1` and each of your saved skills.

## Limits

| Limit | What is refused |
| --- | --- |
| 500 tools | A request names at most 500 tools. |
| 100 tool calls | A run holds at most 100 tool calls. More is `history_too_long`. |
| 100,000 characters | The user messages, taken together, and the system and developer messages, taken together, are each at most 100,000 characters. More is `too_long`. |

A skill is at most 20,000 characters. That limit is on the [skills](/docs/skills) page.

## Errors

These chat completion errors use the OpenAI error shape. `type` is `invalid_request_error`. `param` is set when one field is at fault.

```json
{
  "error": {
    "message": "Send the task as a user message",
    "type": "invalid_request_error",
    "code": "request_required"
  }
}
```

| Code | Status | When |
| --- | --- | --- |
| `invalid_settings` | 400 | `settings` was not accepted. `param` names the setting. |
| `invalid_skill_id` | 400 | `X-Skill-Id` is not `skl_` and 32 hex characters. |
| `invalid_skill_version` | 400 | `X-Skill-Version` is not a whole number from 1. |
| `history_too_long` | 400 | The run has more than 100 tool calls. The message is `A run is limited to 100 tool calls`. |
| `too_long` | 400 | User messages, or system and developer messages, are over 100,000 characters. The message is `User and system messages are limited to 100,000 characters each`. |
| `tool_result_missing` | 400 | A tool call in the history has no tool message. |
| `request_required` | 400 | There is no user message. The message is `Send the task as a user message`. An image with no text still counts as a user message. |
| `invalid_reasoning` | 400 | `reasoning_effort` and `reasoning.effort` ask for different efforts. |
| `insufficient_credit` | 402 | The account has no credit left. Nothing runs. The message is `The account has no credit left`. |

`401` and `403` are the same refusals as on the [API keys](/docs/api-keys) page: a wrong or missing key, or an account that has not redeemed an invite or is disabled.

`429` means the account already has 4 requests running. The body is `{ "error": "too_many_requests" }`, the response has a `Retry-After` header, and the request is not charged. The same limit is on the [credits](/docs/credits) page.

## Related

- [Quickstart](/docs/quickstart)
- [Skills](/docs/skills)
- [API keys](/docs/api-keys)
- [Credits and billing](/docs/credits)
