Create a chat completion

POST /api/v1/chat/completions — send a conversation to Ostra Pro. OpenAI Chat Completions compatible, streamed or not.

POSThttps://ostra.testrelic.ai/api/v1/chat/completions

Sends a conversation to Ostra Pro and returns its reply. OpenAI Chat Completions compatible, streamed or not.

Any OpenAI client works: set its base URL to https://ostra.testrelic.ai/api/v1 and its API key to your Ostra key. Thinking is on by default; set its depth with reasoning_effort, or turn it off with chat_template_kwargs.enable_thinking: false.

Fields not listed below (for example top_p, stop, seed, response_format, tool_choice) are passed to the model unchanged.

Auth
Authorization: Bearer $OSTRA_API_KEY or x-api-key: $OSTRA_API_KEY. Needs a Full-access key.
Rate limit
Counts against your workspace's requests per minute.
Cost
Input $0.64, cached input $0.06, output $4.47 per 1M tokens; reasoning tokens bill as output. The most a request can cost is held from your balance up front and the rest is refunded when it ends. Failed requests and cold-start timeouts cost nothing; a stream that breaks bills only the tokens produced.
Over MCP
Same operation as the ostra_pro_chat tool.
curl https://ostra.testrelic.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OSTRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'x-ostra-session: checkout-suite-run-42' \
  -d '{
    "model": "ostra-pro",
    "messages": [
      {
        "role": "system",
        "content": "You are a senior test engineer. Answer briefly."
      },
      {
        "role": "user",
        "content": "This Playwright test times out on CI but passes locally. Why, and how do I fix it?"
      }
    ],
    "reasoning_effort": "low",
    "max_tokens": 1024
  }'
Headers
x-request-id
req_01JDXK4M7Q2N8R5T6V9W3Y1Z0A
ostra-ratelimit-requests-limit
600
ostra-ratelimit-requests-remaining
599
ostra-ratelimit-requests-reset
42
ostra-model-version
1.0
ostra-cost-usd
0.00079318
ostra-balance-remaining-usd
24.99920682
{
  "id": "chatcmpl-7f3a9c1e2b4d",
  "object": "chat.completion",
  "created": 1795615200,
  "model": "ostra-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "CI machines are slower and run tests in parallel, so the coupon button renders after your 30 s timeout. Wait for the state you need instead of a fixed time: `await expect(page.getByRole('button', { name: 'Apply coupon' })).toBeEnabled()` before clicking, and stop sharing the cart between tests so parallel workers don’t race.",
        "reasoning_content": "Timeout only on CI: likely slower runners or shared state between parallel tests…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 52,
    "completion_tokens": 170,
    "total_tokens": 222,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}

Request headers

  • x-ostra-sessionstring

    Optional. One value per conversation or agent run (1–128 letters, digits, _, ., : or -). Requests with the same value are routed to the same model replica when possible, so more of the conversation’s earlier turns are served from the prompt cache and bill as cached input. Best effort: an unknown value or a different replica just means no cache hit. See Sessions and caching.

    pattern ^[\w.:-]{1,128}$

Request body

  • modelstringRequired

    Always ostra-pro.

    Valueostra-pro
  • messagesarray of objectsRequired

    The conversation so far. Up to 8 images and 1 video per request.

    1–4,000 items
    Show 5 child fields
    • rolestringRequired

      Who wrote the message.

      One ofsystemdeveloperuserassistanttool
    • contentstring or array of parts or null

      Text, or an array of parts: { "type": "text", "text" }, { "type": "image_url", "image_url": { "url" } } (https or data:image/...;base64, URL) or { "type": "video_url", "video_url": { "url" } }.

    • tool_callsarray of objects

      On assistant messages: the tool calls the model made, sent back as you received them.

    • tool_call_idstring

      On tool messages: the id of the call this message answers.

    • namestring

      Optional participant name.

  • max_completion_tokensinteger

    Most output tokens to generate, reasoning included. Values above 32,768 are lowered to 32,768. Takes precedence over max_tokens.

    ≥ 1default 8192
  • max_tokensinteger

    Same as max_completion_tokens (older name).

    ≥ 1default 8192
  • streamboolean

    Stream the reply as server-sent events. See Streaming.

    default false
  • stream_optionsobject

    With stream. Set include_usage: true to get a final chunk with token usage.

    Show 1 child field
    • include_usageboolean

      Send a usage-only chunk before [DONE].

  • reasoning_effortstring

    How long the model thinks before answering. Lower is faster and cheaper.

    One oflowmediumxhighdefault "xhigh"
  • chat_template_kwargsobject

    Model template switches.

    Show 1 child field
    • enable_thinkingboolean

      false answers directly, with no reasoning.

      default true
  • toolsarray of objects

    Functions the model may call, in OpenAI format.

    0–128 items
    Show 2 child fields
    • typestringRequired

      Always function.

      Valuefunction
    • functionobjectRequired

      { "name", "description", "parameters" }, where parameters is a JSON Schema.

  • tool_choicestring or object

    auto (default), none, required, or a specific function, as in OpenAI.

  • temperaturenumber

    Sampling temperature.

    0 to 2
  • ninteger

    Only 1 is supported.

    Value1

Response

  • idstring

    Completion id.

  • objectstring

    chat.completion (or chat.completion.chunk when streaming).

  • createdinteger

    Unix time.

  • modelstring

    ostra-pro.

  • choicesarray of objects

    One choice.

    Show 3 child fields
    • indexinteger

      Always 0.

    • messageobject

      The reply.

      Show 4 child fields
      • rolestring

        assistant.

      • contentstring or null

        The answer text.

      • reasoning_contentstring or null

        The model’s reasoning, when thinking is on.

      • tool_callsarray of objects

        Tool calls the model wants you to run: { "id", "type": "function", "function": { "name", "arguments" } }.

    • finish_reasonstring

      stop, length (hit the token limit) or tool_calls.

  • usageobject

    Token counts this request was billed for.

    Show 4 child fields
    • prompt_tokensinteger

      Input tokens, cached ones included.

    • completion_tokensinteger

      Output tokens, reasoning included.

    • total_tokensinteger

      Sum of the two.

    • prompt_tokens_detailsobject

      Breakdown of input.

      Show 1 child field
      • cached_tokensinteger

        Input tokens served from the prompt cache, billed at the cached rate.

Response headers

  • x-request-idstring

    Id of this request (req_ + 26 characters). Quote it to support.

  • ostra-ratelimit-requests-limitinteger

    Your workspace’s requests-per-minute limit.

  • ostra-ratelimit-requests-remaininginteger

    Requests left in the current minute.

  • ostra-ratelimit-requests-resetinteger

    Seconds until the current minute ends and the count resets.

  • ostra-model-versionstring

    Ostra Pro version that answered: 1.0.

  • ostra-cost-usdstring

    Non-streaming only: what this request cost.

  • ostra-balance-remaining-usdstring

    Workspace credit balance after this request, in USD. Approximate under concurrent requests.

Errors

StatusTypeWhen
400invalid_requestValidation failed (param names the field), or the model rejected the request.
413payload_too_largeThe body is larger than 5.5 MB (images and video count).
401authentication_errorThe API key is missing, malformed, unknown, revoked or expired.
403permission_errorThe caller’s IP isn’t in the key’s allowlist, or a read-only key called a route that needs full access.
402insufficient_balanceYour balance doesn’t cover the request’s maximum cost. Top up or lower max_tokens.
402spend_limit_reachedThe workspace’s monthly spend limit (scope: "org") or this key’s monthly spend cap (scope: "key") is reached.
429rate_limit_exceededThe workspace’s requests-per-minute limit is reached. Wait Retry-After seconds.
502upstream_errorOstra Pro failed to answer. Nothing was charged.
503service_unavailableOstra Pro is starting after a quiet period (state: "starting", retry after 60 s) or at capacity (retry after 5 s). Nothing was charged.

Every error has the same envelope and a request_id. See Errors for messages and retry advice.

Was this page helpful?