# OpenAI Responses API

`POST /v1/responses`

The OpenAI Responses API, used to create model responses.
Supports multi-turn conversations, tool calls, reasoning and more.

## Authorizations

Bearer authentication — send `Authorization: Bearer <token>`.

## Request Body (application/json) — required

```json
{
  "type": "object",
  "required": [
    "model"
  ],
  "properties": {
    "model": {
      "type": "string"
    },
    "input": {
      "description": "Input — either a string or an array of messages",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {}
          }
        }
      ]
    },
    "instructions": {
      "type": "string"
    },
    "max_output_tokens": {
      "type": "integer"
    },
    "temperature": {
      "type": "number"
    },
    "top_p": {
      "type": "number"
    },
    "stream": {
      "type": "boolean"
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      }
    },
    "tool_choice": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "properties": {}
        }
      ]
    },
    "reasoning": {
      "type": "object",
      "properties": {
        "effort": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high"
          ]
        },
        "summary": {
          "type": "string"
        }
      }
    },
    "previous_response_id": {
      "type": "string"
    },
    "truncation": {
      "type": "string",
      "enum": [
        "auto",
        "disabled"
      ]
    }
  }
}
```

## Responses

### 200 — Response created

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "object": {
      "type": "string",
      "example": "response"
    },
    "created_at": {
      "type": "integer"
    },
    "status": {
      "type": "string",
      "enum": [
        "completed",
        "failed",
        "in_progress",
        "incomplete"
      ]
    },
    "model": {
      "type": "string"
    },
    "output": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "content": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "usage": {
      "type": "object",
      "properties": {
        "prompt_tokens": {
          "type": "integer",
          "description": "Prompt tokens"
        },
        "completion_tokens": {
          "type": "integer",
          "description": "Completion tokens"
        },
        "total_tokens": {
          "type": "integer",
          "description": "Total tokens"
        },
        "prompt_tokens_details": {
          "type": "object",
          "properties": {
            "cached_tokens": {
              "type": "integer"
            },
            "text_tokens": {
              "type": "integer"
            },
            "audio_tokens": {
              "type": "integer"
            },
            "image_tokens": {
              "type": "integer"
            }
          }
        },
        "completion_tokens_details": {
          "type": "object",
          "properties": {
            "text_tokens": {
              "type": "integer"
            },
            "audio_tokens": {
              "type": "integer"
            },
            "reasoning_tokens": {
              "type": "integer"
            }
          }
        }
      }
    }
  }
}
```