---
title: "Create a stateless response"
method: POST
path: "/responses"
---

# Create a stateless response

`POST /responses`

## Request

- Base URL: `https://www.ninjachat.ai/api/v1`
- URL: `https://www.ninjachat.ai/api/v1/responses`
- Auth: HTTP bearer

OpenAI Responses-compatible text, vision, structured-output, and function-calling API. Set stream=true for typed lifecycle events.

## Headers

- `Idempotency-Key` string

## Request body

- ResponsesRequest
  - `model` string
  - `models` string[]
  - `input` union, required
    - string
    - union[]
      - union
        - object
          - `type` 'message'
          - `role` 'developer' | 'system' | 'user' | 'assistant', required
          - `content` union, required
            - string
            - union[]
              - …
        - object
          - `type` 'function_call', required
          - `call_id` string, required
          - `name` string, required
          - `arguments` string, required
        - object
          - `type` 'function_call_output', required
          - `call_id` string, required
          - `output` union, required
            - string
            - union[]
              - …
  - `instructions` string
  - `max_output_tokens` integer: Maximum completion tokens, including reasoning where the provider counts it. Must fit the selected provider's output and context limits. Defaults to 2048 when omitted.
  - `temperature` number
  - `top_p` number
  - `stream` boolean
  - `store` false
  - `tools` object[]
    - `type` 'function', required
    - `name` string, required
    - `description` string
    - `parameters` object
    - `strict` boolean
  - `tool_choice` union
    - 'none' | 'auto' | 'required'
    - object
      - `type` 'function', required
      - `name` string, required
  - `parallel_tool_calls` boolean
  - `text` object
    - `format` union
      - object
        - `type` 'text', required
      - object
        - `type` 'json_object', required
      - object
        - `type` 'json_schema', required
        - `name` string, required
        - `description` string
        - `schema` object, required
        - `strict` boolean
  - `reasoning` ChatReasoning
    - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
    - `max_tokens` integer
    - `enabled` boolean
  - `routing` RoutingPolicy
    - `strategy` 'balanced' | 'cost' | 'latency' | 'quality'
    - `providers` object
      - `only` string[]
      - `exclude` string[]
      - `order` string[]
    - `allow_fallbacks` boolean
    - `require_parameters` boolean
    - `data_policy` 'default' | 'no_training' | 'zero_retention'
    - `caching` 'auto'
    - `max_cost_usd` number
  - `metadata` object
  - `user` string

## Response `200`

Completed response or SSE stream.

- ResponseObject
  - `id` string, required
  - `object` 'response', required
  - `created_at` integer, required
  - `status` 'completed' | 'incomplete', required
  - `error` unknown, required
  - `incomplete_details` object, nullable, required
    - `reason` 'max_output_tokens' | 'content_filter', required
  - `instructions` string, nullable, required
  - `max_output_tokens` integer, nullable, required
  - `model` string, required
  - `output` union[], required
    - union
      - object
        - `id` string, required
        - `type` 'reasoning', required
        - `status` 'completed' | 'incomplete', required
        - `summary` object[], required
          - `type` 'summary_text', required
          - `text` string, required
      - object
        - `id` string, required
        - `type` 'message', required
        - `status` 'completed' | 'incomplete', required
        - `role` 'assistant', required
        - `content` object[], required
          - `type` 'output_text', required
          - `text` string, required
          - `annotations` unknown[], required
            - unknown
      - object
        - `id` string, required
        - `type` 'function_call', required
        - `status` 'completed' | 'incomplete', required
        - `call_id` string, required
        - `name` string, required
        - `arguments` string, required
  - `output_text` string, required
  - `parallel_tool_calls` boolean, required
  - `previous_response_id` unknown, required
  - `store` false, required
  - `usage` object, required
    - `input_tokens` integer, required
    - `input_tokens_details` object, required
      - `cached_tokens` integer, required
      - `cache_creation_tokens` integer, required
    - `output_tokens` integer, required
    - `output_tokens_details` object, required
      - `reasoning_tokens` integer, required
    - `total_tokens` integer, required
  - `cost_usd` number, required
  - `provider` string, nullable, required
  - `request_id` string, required
  - `routing` RoutingSummary, required
    - `strategy` 'balanced' | 'cost' | 'latency' | 'quality', required
    - `requested_models` string[], required
    - `resolved_model` string, required
    - `provider` string, nullable, required
    - `provider_attempts` ProviderAttemptReceipt[]
      - `provider` string, required
      - `outcome` 'served' | 'failed_over' | 'failed', required
      - `attempt_index` integer, required
    - `fallbacks_allowed` boolean, required
    - `data_policy` 'default' | 'no_training' | 'zero_retention', required
    - `caching` 'auto'
    - `source` 'request' | 'project' | 'default'
    - `router` RouterDecisionSummary
      - `id` 'ninja/auto', required
      - `task` string, required
      - `classified_by` 'regex' | 'llm' | 'llm-cached', required
      - `override` 'long_context' | 'multilingual', nullable, required
      - `reasoning` string, required
      - `candidates` string[], required
      - `considered` object[], required
  - `metadata` object, required

## Other responses

- `400`: Invalid or unsupported request parameter.
- `401`: Missing or invalid API key.
- `402`: Insufficient balance or project spend limit reached.
- `429`: Rate limit exceeded.
- `500`: Gateway error.

---

[API](https://skmtc.dev/ninjachat/apis/ninjachat-api.md) · [All operations](https://skmtc.dev/ninjachat/apis/ninjachat-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ninjachat/apis/ninjachat-api/revisions/fa7dfcbdcb03?raw)