---
title: "Create a response (OpenAI-compatible, non-streaming)"
method: POST
path: "/v1/responses"
tags: ["OpenAI Compatible", "Completions", "Responses", "Non-Streaming", "LLM", "v1"]
---

# Create a response (OpenAI-compatible, non-streaming)

`POST /v1/responses`

## Request

- Base URL: `https://api.swarms.world`
- URL: `https://api.swarms.world/v1/responses`
- Auth: none declared. Required headers: `x-api-key`

Creates a standard (non-streaming) completion response, compatible with the OpenAI response format. Use this endpoint as a drop-in replacement to create responses similar to OpenAI's chat/completions, but always returns the full response in a single payload. Requires API key authentication and is subject to rate limiting. Common use cases include chatbot interactions, assistant replies, and single-turn LLM completions.

## Headers

- `x-api-key` string, required

## Request body

- ResponseRequest: Request body for POST /v1/responses. Any other field set to a non-empty value, such as stream, tools or previous_response_id, returns 400 until it is supported.
  - `model` string, required: Model to use. See GET /v1/models/available for the models you can use.
  - `input` union, required: The user's text, or a list of message items with role user, assistant, system or developer. Message content is a string or a list of input_text and output_text parts. At least one user message is required; other item types and image or file parts return 400.
    - string
    - object[]
  - `instructions` string, nullable: System prompt. Joined with any system or developer messages in input, in that order.
  - `max_output_tokens` integer, nullable: Maximum number of tokens to generate. When the limit is reached, status is incomplete with reason max_output_tokens.
  - `temperature` number, nullable: Sampling temperature, 0 to 2. Omitted by default so the model's own default applies.
  - `top_p` number, nullable: Nucleus sampling cutoff.

## Response `200`

Successful Response

- ResponseObject: A completed or incomplete response, in the OpenAI Responses API shape.
  - `id` string, required: Response identifier, resp_ prefixed.
  - `object` 'response'
  - `created_at` integer, required: Unix time the response was created.
  - `model` string, required: The model that answered.
  - `status` 'completed' | 'incomplete', required: incomplete when max_output_tokens cut the answer short.
  - `incomplete_details` IncompleteDetails
    - `reason` 'max_output_tokens', required: Why generation stopped early.
  - `error` unknown
  - `output` ResponseOutputMessage[], required: One assistant message.
    - `type` 'message'
    - `id` string, required: Message identifier, msg_ prefixed.
    - `role` 'assistant'
    - `status` 'completed' | 'incomplete', required: Same as the response status.
    - `content` ResponseOutputText[], required: One output_text part.
      - `type` 'output_text'
      - `text` string, required: The generated text.
      - `annotations` unknown[]: Always empty.
        - unknown
  - `usage` ResponseUsage, required
    - `input_tokens` integer, required: Prompt tokens billed.
    - `output_tokens` integer, required: Generated tokens billed.
    - `total_tokens` integer, required: input plus output.
    - `input_tokens_details` InputTokensDetails, required
      - `cached_tokens` integer: Always 0; prompt caching is not reported.
    - `output_tokens_details` OutputTokensDetails, required
      - `reasoning_tokens` integer: Always 0; reasoning tokens are not reported.

## Other responses

- `400`: An unsupported field or input item, named in the message
- `404`: Unknown model
- `422`: Validation Error

## Changes

- **2026-10-22** `90470f3738e6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/swarms/apis/swarms-api/changes/v1/responses/post.md)

---

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