Responses

Supported Models

Only models specifically designed for the "responses" API type can be used with this endpoint. Using a model of type chat/completion or any other type will result in an error.

Headers

Request Body

This endpoint expects a JSON object in the request body with the following fields:

Example Request & Response

Here's a complete example showing how the endpoint works:

{
  "model": "provider-5/gpt-5-codex",
  "input": [
    {
      "role": "user",
      "content": "Analyze the correlation between user engagement and feature adoption."
    }
  ],
  "instructions": "You are a data analyst. Provide step-by-step reasoning before your final answer.",
  "max_tokens": 1024,
  "temperature": 0.5
}

{
  "id": "resp_abc123def456",
  "object": "response",
  "created_at": 1729584251,
  "model": "provider-5/gpt-5-codex",
  "output": [
    {
      "id": "reasoning_1",
      "type": "reasoning",
      "content": [
        "Step 1: Acknowledge the user's request to find a correlation.",
        "Step 2: Formulate a plan to analyze the data.",
        "Step 3: Perform the correlation calculation.",
        "Step 4: Structure the final answer as a JSON object."
      ],
      "summary": [
        "User wants correlation analysis. I will outline steps and provide final JSON output."
      ]
    },
    {
      "id": "msg_xyz789",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "{\"correlation_factor\": 0.82, \"summary\": \"Strong positive correlation found...\"}",
          "annotations": [],
          "logprobs": []
        }
      ],
      "status": "completed"
    }
  ],
  "usage": {
    "prompt_tokens": 56,
    "completion_tokens": 121,
    "total_tokens": 177
  }
}

Response Body (200 OK)

A successful request returns a JSON object with a structured output array that separates the model's reasoning from its final message:

Rate Limiting

This endpoint is rate-limited. Your current limits are returned in the following response headers on every successful request:

• X-RateLimit-Limit-Minute: Your RPM (Requests Per Minute) limit
• X-RateLimit-Remaining-Minute: Requests remaining in the current minute
• X-RateLimit-Reset-Minute: The UTC timestamp when your minute limit will reset
• X-RateLimit-Limit-Day: Your RPD (Requests Per Day) limit
• X-RateLimit-Remaining-Day: Requests remaining in the current day
• X-RateLimit-Reset-Day: The UTC timestamp when your daily limit will reset

Error Handling

The endpoint uses standard HTTP status codes to indicate the success or failure of a request:

• 400 Bad Request: The request payload is invalid. This can be due to malformed JSON, missing required fields like model or input, or using a model that is not of type responses.
• 401 Unauthorized: Your API key is missing, invalid, or expired.
• 403 Forbidden: Your API key is valid but does not have permission to perform the request. This can occur if the model is disabled by an administrator, not available for your current subscription plan, on your API key's blacklist, or your API key has a whitelist and the model is not on it.
• 404 Not Found: The requested model ID does not exist.
• 429 Too Many Requests: You have exceeded your rate limit (RPM or RPD).
• 500 Internal Server Error: An unexpected error occurred on the server.
• 501 Not Implemented: The provider for the requested model does not support the /v1/responses endpoint.

Key Differences from /v1/chat/completions

While both endpoints generate text, they are designed for different purposes: