---
title: "POST /v1/responses"
method: POST
path: "/v1/responses"
---

# POST /v1/responses

`POST /v1/responses`

Create a response with the OpenAI-compatible Responses API. The NanoGPT Advisor extension is available for non-streaming, foreground, platform-billed pay-as-you-go API-key requests that do not use client tools, structured output, inline moderation, BYOK, accountless payment, memory, or server-side content enhancements.

## Headers

- `X-Provider` string
- `X-Billing-Mode` string
- `X-Team-Id` string
- `x-x402` 'true'

## Request body

- ResponsesCreateRequest
  - `model` string, required — Model ID to use for the response. Provider-selection-capable models may include routing preference suffixes such as ':fast', ':speed', ':cheap', ':price', ':latency', ':throughput', ':floor', ':tools', ':caching', ':cache', or ':cached'.
  - `billing_mode` string — Billing override to force pay-as-you-go without an explicit provider, or to apply saved provider preferences to subscription-included traffic. Accepted values (case-insensitive): paygo, pay-as-you-go, pay_as_you_go, paid, payg.
  - `billingMode` string — Alias for billing_mode.
  - `input` union, required — Prompt string or array of input items
    - string
    - object[]
  - `instructions` string — System instructions for the model
  - `max_output_tokens` integer — Maximum tokens in the response
  - `temperature` number — Sampling temperature (not supported by reasoning models)
  - `top_p` number — Nucleus sampling parameter
  - `tools` object[] — Function tools available to the model
  - `tool_choice` union — How the model should use tools
    - string
    - object
  - `parallel_tool_calls` boolean — Allow multiple tool calls in parallel
  - `stream` boolean — Enable streaming responses
  - `store` boolean — Store the response locally for later retrieval/threading/background processing. Set false to disable stored Responses API data for the request.
  - `retention_days` integer, nullable — Per-request retention override in days (0..365). Use 0 to disable retention for the request; use null to fall back to configured defaults.
  - `retentionDays` integer, nullable — Alias for retention_days (0..365). If both are provided, values must match.
  - `previous_response_id` string — Link to previous response for conversation threading
  - `reasoning` object — Reasoning configuration. Setting `reasoning.effort` to any non-`none` value explicitly requests reasoning mode.
  - `text` object — Text/format configuration
  - `metadata` object — Custom metadata
  - `truncation` 'auto' | 'disabled' — Truncation strategy
  - `user` string — Unique user identifier
  - `seed` integer — Optional integer forwarded on model/provider routes that support seeded sampling. This may improve reproducibility but does not guarantee identical output. Results can change if NanoGPT selects a different automatic or fallback route, or if the provider changes its backend.
  - `background` boolean — Enable background/async processing
  - `service_tier` 'auto' | 'default' | 'flex' | 'priority' — Optional service tier: "auto", "default", "flex", or "priority". Use "flex" for lower-cost variable-capacity processing or "priority" for higher-cost priority processing where supported by the routed model/provider.
  - `advisor` AdvisorConfig — Allows the executor model to consult one different advisor model. Auto mode lets the executor decide whether to consult; required mode forces one consultation request. Advisor is non-streaming and available only for platform-billed pay-as-you-go API-key requests. Subscriptions, BYOK, accountless x402, Private Mode, inline moderation, client tools, structured outputs, memory, and server-side content enhancements are rejected before orchestration. Each completed executor, advisor, and continuation phase is billed separately.
    - `model` string, required — Explicit advisor model ID. Automatic model selection and the executor's resolved model are not allowed.
    - `instructions` string
    - `mode` 'auto' | 'required' — Auto lets the executor decide whether to consult. Required forces exactly one internal consultation request before the final answer.
    - `max_uses` 1
    - `max_completion_tokens` integer — Optional advisor output-token limit. When omitted, NanoGPT does not impose an Advisor-specific output cap and the selected model/provider defaults apply.
    - `forward_transcript` false

## Response `200`

Response created

- ResponsesResponse — Response object returned by the Responses API
  - `id` string
  - `object` string
  - `created_at` integer
  - `model` string
  - `status` 'queued' | 'in_progress' | 'completed' | 'incomplete' | 'failed' | 'cancelled'
  - `output` object[]
  - `output_text` string
  - `usage` object
  - `error` object
  - `incomplete_details` object
  - `metadata` object
  - `service_tier` string
  - `advisor` AdvisorResponseMetadata — Advisor orchestration outcome. Top-level usage and pricing aggregate billable phases that returned usage, including an HTTP-success advisor phase whose output was unusable; the optional per-phase objects provide reconciliation detail.
    - `id` string, required
    - `mode` 'auto' | 'required', required
    - `executor_model` string, required
    - `advisor_model` string, required
    - `requested` boolean, required — Whether the executor emitted the internal consultation request.
    - `consulted` boolean, required — Whether an advisor child call was attempted.
    - `successful` boolean, required — Whether the advisor returned usable advice.
    - `consultation_count` 0 | 1, required
    - `max_uses` 1, required
    - `status` 'not_used' | 'completed' | 'failed', required
    - `error` string — Present when consultation failed but the executor could continue.
    - `usage` AdvisorPhaseBreakdown
      - `executor` object
      - `advisor` object
      - `continuation` object
      - `total` object
    - `pricing` AdvisorPhaseBreakdown
      - `executor` object
      - `advisor` object
      - `continuation` object
      - `total` object

## Other responses

- `400` — Bad Request - Invalid parameters
- `401` — Unauthorized - Invalid or missing API key
- `402` — Payment Required - authenticated insufficient balance or opted-in accountless x402 quote for supported non-streaming requests
- `429` — Too Many Requests - Rate limit exceeded

---

[API](https://skmtc.dev/nano-gpt/apis/nanogpt-api.md) · [All operations](https://skmtc.dev/nano-gpt/apis/nanogpt-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nano-gpt/nanogpt-api/revisions/584e96d146b0/schema)