> For the complete documentation index, see [llms.txt](https://docs.cortecs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortecs.ai/api-overview/responses-beta.md).

# Responses \[BETA]

## Create a model response

> This endpoint creates a response using the specified model.

```json
{"openapi":"3.0.0","info":{"title":"Cortecs Responses API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ResponseRequest":{"type":"object","description":"A request object for generating model responses and controlling router behavior. This object contains suggested parameters to generate a response from the specified model. Many parameters are optional, and you may include other parameters as required. Not all providers support the same parameters. Unsupported parameters can cause requests to fail or limit the providers able to process them.\n","properties":{"preference":{"type":"string","description":"The provider preference for handling the request.","enum":["speed","cost","balanced"]},"allowed_providers":{"type":"array","items":{"type":"string"},"description":"The providers that are allowed to be used for the completion.","nullable":true},"eu_native":{"type":"boolean","description":"Whether to consider only providers based and regulated withing the EU. Even when false, all our endpoints are GDPR compliant.","nullable":true},"allow_quantization":{"type":"boolean","description":"Whether to allow quantized endpoints.","nullable":true},"allow_zero_data_retention":{"type":"boolean","description":"Whether to use only ZDR providers.","nullable":true},"enable_model_fallback":{"type":"boolean","description":"Whether to allow model fallback when a model is currently unavailable.","nullable":true},"fallbacks":{"type":"array","items":{"type":"string"},"description":"The providers that are allowed to be used for the completion.","nullable":true},"model":{"type":"string","description":"The model to use for the response."},"input":{"description":"The text, messages, or tool outputs to send to the model.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"object"}}]},"instructions":{"type":"string","description":"Instructions that guide the model's response.","nullable":true},"max_output_tokens":{"type":"integer","description":"The maximum number of tokens to generate.","nullable":true},"temperature":{"type":"number","description":"Controls randomness in the output.","nullable":true},"top_p":{"type":"number","description":"Controls output diversity using nucleus sampling.","nullable":true},"stream":{"type":"boolean","description":"Whether to stream response events.","default":false},"tools":{"type":"array","description":"Tools the model may call.","items":{"type":"object"},"nullable":true},"tool_choice":{"description":"Controls which tool the model may call.","oneOf":[{"type":"string"},{"type":"object"}]},"parallel_tool_calls":{"type":"boolean","description":"Whether the model may call tools in parallel.","nullable":true},"previous_response_id":{"type":"string","description":"The previous response to continue from.","nullable":true},"reasoning":{"type":"object","description":"Reasoning configuration for supported models.","nullable":true},"text":{"type":"object","description":"Text output configuration.","nullable":true},"metadata":{"type":"object","description":"Metadata associated with the response.","additionalProperties":{"type":"string"},"nullable":true}},"required":["model","input"]},"ModelResponse":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the response."},"object":{"type":"string","description":"The type of object returned."},"created_at":{"type":"integer","description":"The Unix timestamp when the response was created."},"status":{"type":"string","description":"The current response status."},"provider":{"type":"string","description":"The provider that generated the response."},"model":{"type":"string","description":"The model that generated the response."},"output":{"type":"array","description":"The output items generated by the model.","items":{"type":"object"}},"output_text":{"type":"string","description":"The combined text generated by the model, when available.","nullable":true},"usage":{"type":"object","description":"Token usage information.","properties":{"input_tokens":{"type":"integer","description":"Number of input tokens."},"output_tokens":{"type":"integer","description":"Number of output tokens."},"total_tokens":{"type":"integer","description":"Total number of tokens used."}}}},"required":["id","object","created_at","status","model","output"]}}},"paths":{"/responses":{"post":{"summary":"Create a model response","description":"This endpoint creates a response using the specified model.","operationId":"createResponse","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseRequest"}}}},"responses":{"200":{"description":"A model response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelResponse"}},"text/event-stream":{"schema":{"type":"string","description":"A stream of response events."}}}},"500":{"description":"Internal server error."}}}}}}
```