> ## Documentation Index > Fetch the complete documentation index at: https://omnirelay.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create responses > Calls an enabled model with its protocol-specific reviewed capabilities. Query GET /v1/models for tools, JSON formats, sampling, reasoning and combination restrictions. Capability review covers every callable route. New combinations are documentation-based, pending individual live validation. Reserves and settles validated usage; disable automatic SDK retries. Responses is stateless/store:false; hosted tools and stored IDs are unsupported. All callable routes use parameter passthrough (parameter_policy upstream-first). Capability lists are guidance, not local rejection lists; ordinary schemas and extension fields are forwarded. Native responses/reasoning output is retained. Model provider 400/422 rejections release holds; provider failures, timeouts and interrupted streams need reconciliation. ## OpenAPI ````yaml /openapi.json post /v1/responses openapi: 3.1.0 info: title: OmniRelay API version: 1.0.0 description: >- OpenAI-compatible gateway for reviewed real text models. Access is workspace-specific; query your own model list for capabilities and customer prices. servers: - url: https://api.omnirelay.ai security: - bearerAuth: [] tags: - name: Service - name: Models - name: Chat - name: Management - name: Responses - name: Embeddings - name: Images - name: Videos paths: /v1/responses: post: tags: - Responses summary: Create response description: >- Calls an enabled model with its protocol-specific reviewed capabilities. Query GET /v1/models for tools, JSON formats, sampling, reasoning and combination restrictions. Capability review covers every callable route. New combinations are documentation-based, pending individual live validation. Reserves and settles validated usage; disable automatic SDK retries. Responses is stateless/store:false; hosted tools and stored IDs are unsupported. All callable routes use parameter passthrough (parameter_policy upstream-first). Capability lists are guidance, not local rejection lists; ordinary schemas and extension fields are forwarded. Native responses/reasoning output is retained. Model provider 400/422 rejections release holds; provider failures, timeouts and interrupted streams need reconciliation. operationId: createResponses parameters: - name: X-Gateway-Tags in: header required: false description: >- Tags for this call as comma-separated `key=value` pairs, for example `client=acme,env=prod`. Merged with the API key's default tags; the `tags` body field wins on the same key. `X-OmniRelay-Tags` is the same header under its former name and stays accepted. schema: type: string example: client=acme,env=prod - name: X-Gateway-Metadata in: header required: false description: >- Send `enabled` to receive a `gateway_metadata` block describing what the gateway decided. Any other value, or no header, leaves the response unchanged. `X-OmniRelay-Metadata` is the same header under its former name and stays accepted. schema: type: string enum: - enabled requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResponsesRequest' responses: '200': description: Validated result with settled usage and cost. headers: X-Request-ID: description: >- OmniRelay request ID for diagnostics. It is separate from the provider trace, header and response IDs. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ResponsesResponse' text/event-stream: schema: type: string example: >+ event: response.completed data: {"type":"response.completed","response":{"status":"completed"}} '400': description: >- Invalid JSON, tags or parameters; unsupported model capabilities; or context_length_exceeded. Rejected before dispatch. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unsupported_parameter request_id: 2f6c1d0e9a '401': $ref: '#/components/responses/Unauthorized' '402': description: >- inference_budget_or_access_denied: wallet, key or platform budget cannot cover the reservation; member_budget_exceeded: member cap exceeded. Rejected before dispatch. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_balance request_id: 2f6c1d0e9a '403': description: >- `model_not_allowed`: the API key is limited to other models. Nothing is charged. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: model_not_allowed request_id: 2f6c1d0e9a '404': description: >- `model_unavailable`: the model does not exist or is disabled in this workspace. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: model_unavailable request_id: 2f6c1d0e9a '413': description: >- payload_too_large: the request body exceeds 4 MiB (4194304 bytes of UTF-8). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: payload_too_large request_id: 2f6c1d0e9a '429': description: 'rate_limited: the effective account request limit was exceeded.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited request_id: 2f6c1d0e9a '502': description: >- Model provider rejection, transport failure, invalid response or missing/invalid usage. A dispatched call may retain a hold pending reconciliation; this status does not prove the provider did not bill. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- channel_unavailable, live_provider_not_configured, live_provider_unavailable, runtime_maintenance, or storage_unavailable. Credential and maintenance checks reject before dispatch. An ambiguous dispatched request remains pending; do not automatically retry a paid call. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: live_provider_not_configured request_id: 2f6c1d0e9a components: schemas: ResponsesRequest: type: object required: - model - input additionalProperties: true properties: model: type: string input: oneOf: - type: string maxLength: 1048576 - type: array minItems: 1 maxItems: 2000 items: type: object description: >- Text or explicit message/function-call history. Text parts only; hosted tools and stored response references are unsupported. instructions: type: string maxLength: 1048576 max_output_tokens: type: integer minimum: 1 stream: type: boolean default: false store: type: boolean enum: - false default: false tools: type: array minItems: 1 maxItems: 64 items: type: object required: - type - name additionalProperties: false properties: type: type: string enum: - function name: type: string maxLength: 64 description: type: string maxLength: 4096 parameters: type: object strict: type: boolean description: >- Live only when tools are supported. Function tools only; strict tools and JSON Schema keywords require separate support. See the provider integration guide. tool_choice: oneOf: - type: string enum: - auto - none - required - type: object required: - type - name properties: type: type: string enum: - function name: type: string description: >- Use auto, none or required when tool_choice is advertised. Named function selection additionally requires capabilities.named_tool_choice. parallel_tool_calls: type: boolean text: type: object properties: format: type: object properties: type: type: string enum: - text - json_object - json_schema name: type: string schema: type: object strict: type: boolean reasoning: type: object properties: effort: type: string tags: type: object description: >- Tags for this call. At most 10 after merging with the header and the key's default tags. Keys are 1 to 64 characters and stored in lowercase; values are 1 to 128 characters. Both use only letters, digits and `- _ . : /`. Keys starting with `gateway:` or `omnirelay:` are reserved. A `tags` field that is not an object is ignored. additionalProperties: type: string example: client: acme project: invoices description: >- Parameter passthrough: ordinary extension fields are forwarded; authentication, text/function protocol and budget settlement boundaries remain enforced. ResponsesResponse: type: object required: - id - object - status - model - output - usage - cost_microusd properties: id: type: string object: type: string enum: - response created_at: type: integer status: type: string enum: - completed - incomplete error: type: - object - 'null' incomplete_details: type: - object - 'null' model: type: string output: type: array items: type: object store: type: boolean enum: - false usage: type: object required: - input_tokens - output_tokens - total_tokens properties: input_tokens: type: integer minimum: 0 output_tokens: type: integer minimum: 0 total_tokens: type: integer minimum: 0 input_tokens_details: type: object additionalProperties: false properties: cached_tokens: type: integer minimum: 0 cache_write_tokens: type: integer minimum: 0 output_tokens_details: type: object additionalProperties: false properties: reasoning_tokens: type: integer minimum: 0 cost_microusd: type: integer description: >- Settled customer charge in micro-USD, using frozen prices, token partitions, tiers and discount. Round the full sum, apply the discount and round up again. This is the final charge, not the maximum hold. Error: type: object required: - error properties: error: type: object required: - code - message - type properties: code: type: string example: model_unavailable message: type: string example: The model does not exist or is disabled. description: >- Short English description for logs and SDK exceptions. Its wording can change; branch on code. type: type: string example: not_found_error description: >- Error family by HTTP status: invalid_request_error, authentication_error, insufficient_quota, permission_error, not_found_error, conflict_error, rate_limit_error, service_unavailable or api_error. param: type: string maxLength: 200 description: >- Rejected request field path when identifiable; never a parameter value. Responses uses native field names. request_id: type: string description: Present on chat completion, Responses and embeddings errors. responses: Unauthorized: description: '`unauthorized`: the API key is missing, revoked, or invalid.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key created in the OmniRelay console. The owner can view it again in the console after confirming their identity. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.