Responses

The /v1/responses endpoint provides native support for the OpenAI Responses API wire format. Built for autonomous agent loops, multi-step tool execution, and complex reasoning pipelines, this endpoint unifies next-generation response structures behind nRouter's multi-cloud gateway with automatic failover, content guardrails, and zero-markup pricing.

POST https://api.nrouter.ai/v1/responses

Architectural Role & Lifecycle

When handling requests on /v1/responses, nRouter enforces its robust 4-phase preflight lifecycle:

1. Phase 1: In-Memory Key Auth & ACLs: Verifies virtual key hash (sk-nrouter-...) and confirms tenant organization permissions for the selected model.
2. Phase 2: Sliding-Window Rate Limiting: Enforces tenant-level and key-level RPM and TPM ceilings.
3. Phase 3: Content Moderation & Prompt Injection Scoring: Evaluates the input and instructions fields against safety classifiers. If prompt injection is detected, the request is halted with HTTP 400 (x-nr-guardrails: blocked).
4. Phase 4: Credit Reservation: Estimates token consumption based on input tokens and max_output_tokens and places an atomic credit reservation hold. Blocked requests cost $0.
5. Execution & Settlement: Dispatches the call to the upstream provider cloud. If an outage occurs, automatic fallback routing runs. Tokens are counted and spend is settled atomically at end-of-response at the exact list price of the served model.

Request Parameters

The request body must be a JSON object:

Response Payloads

Standard Response Structure

{
  "id": "resp_01j78qwed928374",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.4-mini",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "nRouter simplifies enterprise AI infrastructure by providing unified routing, governance, and billing."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 16,
    "output_tokens": 20,
    "total_tokens": 36
  }
}

Headers Reference

Inbound Request Headers

Outbound Response Headers

SDK Code Examples

import { nRouter } from "@nrouter_ai/sdk";

const client = new nRouter({
  apiKey: process.env.NROUTER_API_KEY,
});

const response = await client.responses.create({
  model: "gpt-5.4-mini",
  instructions: "You are an autonomous incident response assistant.",
  input: "Summarize the root cause of the database connection pool timeout.",
});

console.log(response.output[0].content[0].text);
console.log(`Cost: \$${client.lastResponse?.cost}`);

Error Codes & Failure Modes

{
  "error": {
    "type": "gateway_error",
    "message": "input: field required",
    "code": "invalid_request"
  }
}

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!"        }      ]    }  ]}