Responses

Behavior

POST /responses is an alias. Read output[].content. output_text is an SDK convenience, not a guaranteed raw field. Creation does not guarantee retrieval or cancellation routes.

Endpoint and authentication

POST /v1/responses

Use an XHub API key: Authorization: Bearer . Do not use upstream provider credentials as gateway keys.

Use the gateway root Base URL shown in the playground, without appending /v1; send requests to the full endpoint path above.

Request example

curl "$XHUB_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $XHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_NAME","input":"Hello, introduce yourself."}'

Request parameters

Field	Type	Description
model	string · required	Public model name; deployment must support this protocol.
input	string or array · required	Text or typed input items.
instructions	string	System instruction.
max_output_tokens	integer	Output ceiling.
stream	boolean	Typed SSE events when supported.
tools / tool_choice	array / string or object	Only tools supported by upstream.
previous_response_id	string	Uses gateway history and the original deployment, scoped by caller, request model and endpoint for one hour. Missing or expired context is rejected; instructions are not inherited.

Success response

{
  "id": "resp-example",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 5,
    "total_tokens": 15
  }
}

Field	Type
id	string
object	string
status	string
output	object[]
output[].type	string
output[].role	string
output[].content	object[]
output[].content[].type	string
output[].content[].text	string
usage	object
usage.input_tokens	number
usage.output_tokens	number
usage.total_tokens	number

Errors and troubleshooting

HTTP	Meaning
400	Invalid request. Check JSON, parameters and query.
401	Missing or invalid XHub credential.
403	Permission denied. Check model scope or policy.
429	Limit exceeded. Inspect response details and Retry-After.