Responses

Create a response

Changed on Nov 3, 2026

Creates a model response in the OpenAI Responses dialect and charges the account for the tokens it used. Requires an API key. /v1/chat/completions and /v1/messages serve the same models in the other two dialects.

post/v1/responses

Request

Base URL
https://api.naga.ac
Auth
- HTTP bearer
- or API key in header x-api-key
TypeScript
https://skmtc.dev/naga/apis/nagaai-api/docs/v1/responses/post.ts
A function with typed inputs. Its response is checked against the schema.

Headers

x-naga-routing-strategy'reliability' | 'balanced' | 'latency' | 'throughput' | 'cache'

The order in which NagaAI tries the providers that serve a model. A NagaAI extension.

The routing strategy when the body names none. An unknown name is ignored. A NagaAI extension.

Request body

modelstring required

The model to run, named by an id or alias from NagaAI's catalog. An entry without the chat.completions capability draws a refusal.

instructionsstring nullable

A system instruction put ahead of the conversation.

max_output_tokensinteger nullable

The ceiling on generated tokens, reasoning included. At least 1, and the gateway raises it where the reasoning budget would not fit.

temperaturenumber double nullable

How much randomness goes into the reply, between 0 and 2. A provider may still refuse a value this range allows.

top_pnumber double nullable

The sampling cut-off, between 0 and 1, and an alternative to temperature.

parallel_tool_callsboolean nullable

Whether the model may return several tool calls in one turn. It reaches only some providers.

truncation'auto' | 'disabled' nullable

What to do when the conversation outgrows the context window. It reaches only some providers.

streamboolean

Whether the reply arrives incrementally as the model writes it. An explicit null draws a refusal.

Response

The response. application/json carries one response object; text/event-stream carries the event-typed lifecycle frames.

instructionsstring nullable required

The system instructions the turn ran with, or null.

tool_choiceunknown required

temperatureunknown required

top_punknown required

parallel_tool_callsboolean required

Whether the model could call several tools at once.

metadataunknown required

textunknown required

truncationunknown required

max_output_tokensinteger nullable required

The ceiling on generated tokens the turn ran with, or null.

reasoningunknown

idstring required

This response's identifier, repeated on every frame. No handle to resume from.

object'response' required

What kind of object this is. Always response.

created_atinteger required

When the response was created, in seconds since the Unix epoch.

statusstring required

Where the turn stands, as the provider named it.

modelstring nullable required

The model that answered, by its id in the NagaAI catalog.

Changes

Nov 3, 2026b697d49fa1f9 Revision changes
- breaking
  added to the request property allOf list
- breaking
  removed subschema #2 from the request property anyOf list
- breaking
  removed subschema #2 from the request property anyOf list
- breaking
  removed subschema #1 subschema #5 from the request property anyOf list
- breaking
  removed subschema #1 subschema #2 from the request property anyOf list
- breaking
  removed subschema #1 subschema #2 from the request property anyOf list
- breaking
  request property list-of-types was narrowed by removing types null from media type application/json
- breaking
  request property list-of-types was narrowed by removing types null from media type application/json
- breaking
  request property list-of-types was narrowed by removing types null from media type application/json
- breaking
  request property list-of-types was narrowed by removing types null from media type application/json
- breaking
  request property list-of-types was narrowed by removing types null from media type application/json
- breaking
  request property list-of-types was narrowed by removing types null from media type application/json
- breaking
  added subschema #1: Lifecycle frame subschema #2: Output item frame subschema #3: Content part frame subschema #4: Output text delta frame subschema #5: Output text done frame subschema #6: Annotation frame subschema #7: Content delta frame subschema #8: Reasoning text done frame subschema #9: Refusal done frame subschema #10: Summary text delta frame subschema #11: Summary text done frame subschema #12: Summary part frame subschema #13: Web search call frame subschema #14: Function call arguments delta frame subschema #15: Function call arguments done frame subschema #16: Error frame to the response body oneOf list for the response status (media type: text/event-stream)
- breaking
  the response's body type changed from object to no type for status (media type: application/json)
- breaking
  the response's property type changed from object to no type for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  removed the required property from the response with the status (media type: application/json)
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property from the response with the status (media type: application/json)
- breaking
  removed the required property from the response with the status (media type: application/json)
- breaking
  removed the required property from the response with the status (media type: application/json)
- breaking
  removed the required property from the response with the status (media type: application/json)
- warning
  the request property's max was set to 2.00
- warning
  the request property's max was set to 1.00
- warning
  the request property's min was set to 1.00
- warning
  the request property's min was set to 0.00
- warning
  the request property's min was set to 0.00
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- warning
  removed the optional property from the response with the status (media type: application/json)
- info
  api operation id createResponse removed and replaced with create_response
- info
  added the new optional header request parameter x-naga-routing-strategy
- info
  added the new optional request property
- info
  the request property became nullable
- info
  the request property became nullable
- info
  the request property became nullable
- info
  the request property became nullable
- info
  the request property became nullable
- info
  the request property became nullable
- info
  the request property default value false was removed
- info
  added subschema #1 subschema #2 to the request property oneOf list
- info
  added subschema #1 subschema #2 to the request property oneOf list
- info
  added subschema #1 subschema #2 to the request property oneOf list
- info
  added subschema #1 subschema #2 to the request property oneOf list
- info
  added subschema #1 subschema #2 to the response body allOf list for the response status (media type: application/json)
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added the required property to the response with the status

Operation history