Skip to main content
POST
/
v1
/
responses
curl --request POST \
  --url https://api.naga.ac/v1/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt-4.1-mini",
  "input": "Summarize why caching matters for API performance."
}
'
{
  "id": "<string>",
  "created_at": 123,
  "status": "<string>",
  "model": "<string>",
  "output": [
    {
      "id": "<string>",
      "role": "<string>",
      "content": [
        {
          "text": "<string>",
          "type": "output_text",
          "annotations": [
            {
              "type": "<string>",
              "start_index": 123,
              "end_index": 123,
              "url": "<string>",
              "title": "<string>"
            }
          ],
          "logprobs": [
            {}
          ]
        }
      ],
      "type": "message",
      "status": "<string>"
    }
  ],
  "object": "response",
  "completed_at": 123,
  "incomplete_details": {},
  "previous_response_id": "<string>",
  "instructions": "<string>",
  "error": {
    "message": "<string>",
    "code": "<string>"
  },
  "tools": [
    {
      "type": "function",
      "name": "<string>",
      "description": "<string>",
      "parameters": {},
      "strict": true
    }
  ],
  "tool_choice": "<string>",
  "truncation": "auto",
  "parallel_tool_calls": true,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "top_p": 123,
  "presence_penalty": 123,
  "frequency_penalty": 123,
  "top_logprobs": 123,
  "temperature": 123,
  "reasoning": {
    "effort": "none",
    "summary": "auto"
  },
  "usage": {
    "input_tokens": 123,
    "input_tokens_details": {
      "cached_tokens": 123
    },
    "output_tokens": 123,
    "output_tokens_details": {
      "reasoning_tokens": 123
    },
    "total_tokens": 123
  },
  "max_output_tokens": 123,
  "max_tool_calls": 123,
  "store": true,
  "background": true,
  "service_tier": "<string>",
  "metadata": {},
  "safety_identifier": "<string>",
  "prompt_cache_key": "<string>"
}

Authorizations

​
Authorization
string
header
required

Primary authentication for inference endpoints. Send your Naga API key as Authorization: Bearer <api-key>.

Body

application/json

Stateless gateway schema for OpenAI Responses API request body. Strict request surface: only parameters that map to the gateway's unified model.

​
model
string
required

Model identifier to route the request to.

Example:

"gpt-4.1-mini"

​
input
required

Text or structured input items to the model.

​
instructions
string | null

A system (or developer) message inserted into the model's context.

​
max_output_tokens
integer | null
Required range: x >= 1
​
temperature
number | null
Required range: 0 <= x <= 2
​
top_p
number | null
Required range: 0 <= x <= 1
​
presence_penalty
number | null
​
frequency_penalty
number | null
​
tools
(FunctionTool · object | WebSearchTool · object | WebSearchPreviewTool · object | FileSearchTool · object | ComputerUseTool · object | CodeInterpreterTool · object | McpTool · object | ImageGenerationTool · object | LocalShellTool · object | ShellTool · object | ApplyPatchTool · object | CustomTool · object)[] | null

Corresponds to FunctionTool.

​
tool_choice
Available options:
auto,
none,
required
​
parallel_tool_calls
boolean | null
​
truncation
enum<string> | null
Available options:
auto,
disabled
​
reasoning
ReasoningConfig · object

Corresponds to Reasoning schema.

We keep this as the subset that maps to the gateway's unified reasoning_effort control.

​
text
ResponseTextConfig · object

Corresponds to CreateResponse text parameter.

​
stream
boolean
default:false

Return a Responses API SSE event stream instead of a single JSON response.

Response

JSON response when stream=false, or Responses API Server-Sent Events when stream=true.

​
id
string
required
​
created_at
integer
required
​
status
string
required
​
model
string
required
​
output
(ResponseMessageItem · object | ResponseFunctionCallItem · object | ResponseReasoningItem · object | ResponseImageGenerationCallItem · object)[]
required
​
object
string
default:response
Allowed value: "response"
​
completed_at
integer | null
​
incomplete_details
Incomplete Details · object
​
previous_response_id
string | null
​
instructions
string | null
​
error
ResponseErrorOutput · object
​
tools
(ResponseFunctionTool · object | ResponseWebSearchTool · object | ResponseWebSearchPreviewTool · object | ResponseFileSearchTool · object | ResponseComputerUseTool · object | ResponseCodeInterpreterTool · object | ResponseMcpTool · object | ResponseImageGenerationTool · object | ResponseLocalShellTool · object | ResponseShellTool · object | ResponseApplyPatchTool · object | ResponseCustomTool · object)[]
​
tool_choice
​
truncation
enum<string> | null
Available options:
auto,
disabled
​
parallel_tool_calls
boolean | null
​
text
ResponseTextConfigOutput · object
​
top_p
number | null
​
presence_penalty
number | null
​
frequency_penalty
number | null
​
top_logprobs
integer | null
​
temperature
number | null
​
reasoning
ResponseReasoningConfigOutput · object
​
usage
ResponseUsageOutput · object
​
max_output_tokens
integer | null
​
max_tool_calls
integer | null
​
store
boolean | null
​
background
boolean | null
​
service_tier
string | null
​
metadata
Metadata · object
​
safety_identifier
string | null
​
prompt_cache_key
string | null