LLM invocation

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"}.

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:

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.

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 .

Response

[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.

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 .

Response

{"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. 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:

{"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.

Get started

Core concepts

Project intelligence

Format guides

Reference

Return text

Return JSON

Return JSON matching a schema

Request fields

Authentication and billing

Errors

​Return text

​Return JSON

​Return JSON matching a schema

​Request fields

​Authentication and billing

​Errors

Return text

Return JSON

Return JSON matching a schema

Request fields

Authentication and billing

Errors