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

# LLM invocation

> Send messages and receive text or JSON in the shape your application needs.

`POST /llm/invoke` makes one non-streaming LLM invocation. Supply the
instructions and context in `messages`, and choose the response format.
The result arrives in the HTTP response; there is no task to poll.

Authenticate with your existing `sk_live_*` API key. Set `OVERTEN_API_KEY`
to that key before running these examples. Both `X-API-Key` and
`Authorization: Bearer` are supported.

The examples print the response body directly. Text examples add a trailing
newline; JSON examples use `jq .` to format the response. If `jq` is not
installed, remove `| jq .` to print the JSON as returned.

## Return text

Omit `response_format`, or set it to `{"type": "text"}`.

```bash theme={null}
curl -sS -w '\n' "https://backend.overtenai.com/api/v1/llm/invoke" \
  -H "X-API-Key: $OVERTEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "Rewrite clearly while preserving meaning."},
      {"role": "user", "content": "We would like to inform you that the meeting has been moved to Friday."}
    ]
  }'
```

The body is plain text (`Content-Type: text/plain`), for example:

```text theme={null}
The meeting has been moved to Friday.
```

## Return JSON

Use `response_format: {"type": "json"}` for a JSON value without a fixed
schema. Describe the desired structure in your messages.

```bash theme={null}
curl -sS -w '\n' "https://backend.overtenai.com/api/v1/llm/invoke" \
  -H "Authorization: Bearer $OVERTEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Return a JSON array containing the integers 1, 2, and 3."}],
    "response_format": {"type": "json"}
  }' | jq .
```

```json Response theme={null}
[1, 2, 3]
```

## Return JSON matching a schema

Use `json_schema` when your consumer needs a particular structure. The
backend validates the result against your schema before charging API
credits and returning it. Objects, arrays, and scalar JSON values are supported.

```bash theme={null}
curl -sS -w '\n' "https://backend.overtenai.com/api/v1/llm/invoke" \
  -H "X-API-Key: $OVERTEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Classify this review as positive or negative: The service was excellent."}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "type": "object",
        "properties": {"sentiment": {"type": "string", "enum": ["positive", "negative"]}},
        "required": ["sentiment"],
        "additionalProperties": false
      }
    },
    "user_id": "customer_123",
    "session_id": "workflow_execution_456"
  }' | jq .
```

```json Response theme={null}
{"sentiment": "positive"}
```

There is no added `text`, `result`, or billing envelope. JSON modes return
`Content-Type: application/json`. Schemas use JSON Schema 2020-12;
inline schemas and local `$ref` pointers are supported. External references,
schema IDs, anchors, and dynamic/recursive reference keywords are not supported.

## Request fields

| Field             | Required | Meaning                                                                                                                                                                                   |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messages`        | Yes      | Non-empty list of messages with `role` (`system`, `user`, or `assistant`) and string `content`.                                                                                           |
| `response_format` | No       | `type` is `text` (default), `json`, or `json_schema`. Include `json_schema` only for schema mode.                                                                                         |
| `model`           | No       | A supported model ID listed in the [endpoint reference](/api-reference/public/invoke-an-llm). Omit it or use `auto` for backend defaults. Configured fallback models may handle the call. |
| `user_id`         | No       | End-user attribution for this invocation. Does not change the paying organization.                                                                                                        |
| `session_id`      | No       | Groups usage under a session. Does not load conversation history or deduplicate requests.                                                                                                 |

For conversation context, send the relevant previous messages with each
invocation. Each HTTP request is a new invocation and may incur a charge.

## Authentication and billing

This endpoint inherits the existing API key permissions and rate limits.
Workspace keys require permission to create content. The organization
associated with the API key pays, including for personal-scope API keys.

The existing API balance check runs before the model call. Its minimum for
LLM invocation is **6 credits**; this is an admission floor, not a fixed price.
A successful call costs `ceil(billable_model_cost_usd / 0.0014)` credits,
including applicable backend billing offers. Failed invocations, invalid
output, and rejected requests do not deduct organization API credits.

Optional `user_id` and `session_id` support attribution. They are not needed
to identify the organization, and do not trigger a separate personal credit charge.

Response headers keep accounting information separate from your result:

To inspect these headers, add `-i` to the curl command and remove `| jq .`
if present. This prints the headers followed by the response body.

| Header           | Meaning                                                                        |
| ---------------- | ------------------------------------------------------------------------------ |
| `X-Request-ID`   | Identifier to reference when investigating the invocation or its ledger entry. |
| `X-Credits-Used` | Usage-derived credits for the successful invocation.                           |
| `X-LLM-Model`    | Actual model used, including when a fallback handled the call.                 |

The request ID is an audit identifier, not a document run or a pollable task.
As with document generation, a settlement failure is logged for reconciliation
and does not discard an otherwise successful result.

## Errors

| HTTP status | Meaning                                                                     |
| ----------- | --------------------------------------------------------------------------- |
| `401`       | Missing, invalid, or revoked API key.                                       |
| `402`       | Insufficient organization API credits or an exceeded LLM usage budget.      |
| `403`       | Suspended organization or insufficient permissions.                         |
| `422`       | Invalid request, unsupported model, or invalid schema.                      |
| `429`       | Existing API rate limit exceeded.                                           |
| `502`       | Model failure, invalid output, or missing usage/pricing needed for billing. |
| `504`       | Model timeout after configured fallback attempts.                           |

Runtime errors use FastAPI's `detail` envelope, for example:

```json theme={null}
{"detail": {"success": false, "error": "invalid_response", "message": "The model did not return valid JSON"}}
```

Request validation errors use the standard FastAPI `detail` list.

For predefined writing operations, see [Text editing](/guides/text).