Browse documentation

Responses

Create model responses using the OpenAI Responses API format with integrated tool calling, agentic multi-turn loops, streaming, and exact list pricing.

The /v1/responses endpoint supports the OpenAI Responses API format for autonomous agent loops, multi-step tool execution, and complex reasoning pipelines. Route requests across provider clouds with configurable fallback chains, safety guardrails, and exact provider list pricing with zero markup.

  • Architectural Lifecycle: Preflight validates key ACLs, checks rate limits (RPM/TPM), inspects content, and reserves token credit (or dispatches directly with your saved provider key under Bring your own keys (BYOK) for OpenAI, Anthropic, DeepInfra, Meta, and Alibaba models). Blocked requests return HTTP 400 (x-nr-guardrails: blocked) with $0 spent and $0 held.
  • Failover & Settlement: Failovers occur only where a fallback chain is configured (in Router Settings or nrouter_fallbacks), and spend settles atomically at end-of-response.
POST https://api.nrouter.ai/v1/responses

Request Parameters

ParameterTypeRequiredDefaultDescription
modelstringYes—Model ID (e.g. gpt-5.4-mini, gpt-4o) or nrouter/auto.
inputstring or arrayYes—Input content string or array of input items.
instructionsstringNo—System-level guidance directing model behavior and tone.
toolsarrayNo—Tools available to model (functions, code interpreter, web search).
tool_choicestring or objectNoautoTool invocation mode (auto, required, none, or specific function).
temperaturenumberNo1.0Sampling temperature between 0.0 and 2.0.
max_output_tokensintegerNo—Maximum number of tokens to generate.
streambooleanNofalseWhen true, streams response deltas via Server-Sent Events (SSE).
nrouter_fallbacksstring[]No—1–4 fallback models if primary admission fails ([] allowed on nrouter/auto only).
nrouter_optimize"quality" | "balanced" | "cost"No—Overrides the saved nrouter/auto selection preference ("balanced" by default) for this call (nrouter/auto only).
nrouter_cost_band"low" | "mid" | "high"No"mid"Blended-rate ceiling (< $1, $1 to < $7, $7+ per 1M tokens); valid on nrouter/auto under "cost" only.
nrouter_guardrailsstring[]No—1–8 organization guardrail policy IDs.
nrouter_cachebooleanNotrueWhen false, bypasses the response cache.

Examples

import { nRouter } from "@nrouter_ai/sdk";
const client = new nRouter({ apiKey: process.env.NROUTER_API_KEY });
const { data: res, response: raw } = await client.responses.create({
  model: "gpt-5.4-mini",
  input: "Summarize incident root cause.",
}).withResponse();
console.log(res.output_text, client.nr.meta(raw.headers).cost);

Headers & Errors

Inbound: Authorization: Bearer sk-nrouter-... and Content-Type: application/json. Optional: x-nr-tags, x-nr-compress. Telemetry: x-nr-request-id, x-nr-latency-ms, x-nr-request-cost, x-nr-cost-status, x-nr-model, x-nr-routing, x-nr-attempts, x-nr-guardrails, x-nr-response-cache. See Chat Completions.

HTTP StatusError CodeReason
400 Bad Requestinvalid_requestMissing required input or model fields, invalid tool schemas, nrouter_optimize on a Direct model, or nrouter_cost_band on a Direct model, invalid band, or under "quality" or "balanced".
400 Bad Requestcost_band_unsatisfiableActive nrouter_cost_band ceiling on a "cost"-preference nrouter/auto call left zero eligible models ($0 spent).
400 Bad Requestguardrail_blockedPreflight inspection detected prompt injection or safety policy violation.
401 Unauthorizedinvalid_api_keyVirtual key missing, expired, or invalid.
402 Payment Requiredinsufficient_creditsOrganization balance is insufficient to reserve token hold.
404 Not Foundmodel_not_foundModel identifier not found or unauthorized for tenant.
429 Too Many Requestsrate_limit_exceededVirtual key or organization RPM/TPM ceiling exceeded.
500 / 503 Provider Errorservice_unavailableUpstream outage. 503 triggers fallback only where configured (nrouter_fallbacks).
POST
/v1/responses

Authorization

NRouterApiKey
AuthorizationBearer <token>

Your nRouter virtual key (sk-nrouter-…). Sent as Authorization: Bearer sk-nrouter-….

In: header

Header Parameters

x-nr-compress?string

Request prompt compression: on to compress eligible prompts, off to skip

Value in

  • "on"
  • "off"
x-nr-tags?string

Custom spend and attribution tags (comma-separated key=value pairs)

x-nr-mcp-server?string

Target MCP server ID when routing MCP tool calls or prompts through the gateway

x-nr-client-language?string

Caller SDK runtime language identification (e.g. typescript, python, rust, go)

x-nr-session-id?string

Caller session identifier allowed at edge for grouping related client turns

x-nr-trace?string

Inbound trace detail level override for request lifecycle spans

Value in

  • "off"
  • "stages"
  • "verbose"
x-nr-trace-stages?string

Inbound stage-level trace emission override

Value in

  • "off"
  • "stages"
  • "verbose"
x-nr-trace-id?string

Accepted so a client sending it is not refused; the value is not recorded and not propagated. Every response carries the gateway's own trace ID in this header, never the one sent.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/responses" \  -H "Content-Type: application/json" \  -d '{    "model": "gpt-5.4-mini",    "input": "Explain how prompt injection defense operates before credit reservation."  }'
{  "id": "resp_01",  "object": "response",  "status": "completed",  "output": [    {      "type": "message",      "role": "assistant",      "content": [        {          "type": "output_text",          "text": "Hello!"        }      ]    }  ]}
Was this page helpful?