> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Responses API

> Create stateless model responses for Codex, SDKs, and other OpenAI-compatible clients.

Create a model response with `POST /openai/{region}/v1/responses`. Langdock implements the OpenAI Responses request and response shape for the fields listed below, so you can use the OpenAI SDK `responses.create` method and other Responses-compatible clients with a Langdock API key.

Use this endpoint for Codex and other clients that send Responses `input` items and read Responses `output` items. For integrations that send `messages` and read `choices`, use [OpenAI Chat Completions](/en/developer/completion-api/openai).

## Before You Start

* **API key**: Create a [personal API key](/en/using-langdock/account/personal-api-keys) or ask your workspace admin for a workspace API key with the Completion API scope.

## Base URL

```
https://api.langdock.com/openai/{region}/v1/responses
```

<Warning>
  **Dedicated deployments**

  Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.
</Warning>

## Parameters

Pass a string, message items, or tool results in `input`. Langdock forwards supported values for `instructions`, `max_output_tokens`, `temperature`, `top_p`, `reasoning`, `text`, `metadata`, `include`, `truncation`, `service_tier`, `tools`, `tool_choice`, and `parallel_tool_calls`. The endpoint supports native server-sent event streaming and function tools, including parallel function calls. Which settings apply depends on the selected model.

The `{region}` path value must be `eu`, `us`, or `global`, and must match a region where your model is available. Call `GET /openai/{region}/v1/models` with the same region to list models available in your workspace. The list may differ when your workspace uses [Bring your own key (BYOK)](/en/admin/byok/byok).

## Differences from the OpenAI API

<Warning>
  Langdock does not persist Responses API state. Send the full conversation state in each request.
</Warning>

* Omit `store` or set it to `false`. `store=true` is rejected.
* `previous_response_id` is not supported and is rejected. Pass previous messages and tool results in `input`.
* Background responses are not supported. Omit `background` or set it to `false`.
* Hosted tools such as web search, file search, code interpreter, image generation, computer use, and MCP are not supported.
* Function tools are supported, including parallel function calls.

## Using the OpenAI Python library

Set Langdock as the base URL and use `responses.create`:

```python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.langdock.com/openai/eu/v1",
    api_key="<YOUR_LANGDOCK_API_KEY>",
)

response = client.responses.create(
    model="gpt-5-mini",
    input="Write a short poem about cats.",
    store=False,
)

print(response.output_text)
```

### Stream a response

Set `stream=True` to receive native Responses API events:

```python theme={null}
stream = client.responses.create(
    model="gpt-5-mini",
    input="Write a short poem about cats.",
    store=False,
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")
```

### Continue a stateless tool conversation

Append the returned output items and the matching `function_call_output` to the next request:

```python theme={null}
import json

conversation = [
    {"role": "user", "content": "What is the weather in Berlin?"}
]
tools = [{
    "type": "function",
    "name": "lookup_weather",
    "description": "Get the current weather for a city.",
    "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
        "additionalProperties": False,
    },
}]

response = client.responses.create(
    model="gpt-5-mini",
    input=conversation,
    tools=tools,
    store=False,
)

conversation.extend(response.output)
tool_call = next(item for item in response.output if item.type == "function_call")
conversation.append({
    "type": "function_call_output",
    "call_id": tool_call.call_id,
    "output": json.dumps({"temperature_c": 18, "condition": "sunny"}),
})

final_response = client.responses.create(
    model="gpt-5-mini",
    input=conversation,
    tools=tools,
    store=False,
)

print(final_response.output_text)
```

## Connect Codex

Create a personal API key, then open **Connect your tools > Codex** on [Settings > Account > API keys](https://app.langdock.com/settings/account/api-keys). Choose an available OpenAI-compatible model and follow the generated setup steps for your operating system. The setup points Codex at Langdock's Responses endpoint (`wire_api = "responses"`) and your selected model.

## Rate limits

The default limits are **500 RPM** (requests per minute) and **150,000 TPM** (tokens per minute).

* RPM is enforced per workspace, model, and API key.
* TPM is shared by all API keys using the same model in a workspace.
* On dedicated deployments, admins can configure custom limits per model in **Settings > Workspace > Products > API**.

A rate-limited request returns `429 Too Many Requests`. Successful and rate-limited responses include `x-ratelimit-limit-requests`, `x-ratelimit-limit-tokens`, `x-ratelimit-remaining-requests`, and `x-ratelimit-remaining-tokens`.

Personal API key usage counts toward the member's effective personal budget and the workspace spend limit together with chat and agent usage. Workspace API key usage counts toward the workspace API spend limit. See [Personal API keys](/en/using-langdock/account/personal-api-keys) and [Pricing](/en/admin/billing/pricing#api).

<Info>
  Browser and CORS integrations are not supported. Keep API keys server-side and call the endpoint from a server, CLI, or local development tool. See [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>


## OpenAPI

````yaml POST /openai/{region}/v1/responses
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
    description: Production
security:
  - bearerAuth: []
paths:
  /openai/{region}/v1/responses:
    post:
      tags:
        - Responses
      summary: Creates a stateless model response.
      description: >-
        Creates a stateless OpenAI-compatible response. Supports text
        generation, streaming, and function tools. Do not send store=true,
        previous_response_id, background=true, or hosted tools.
      operationId: createResponse
      parameters:
        - name: region
          in: path
          required: true
          description: The region of the API to use.
          schema:
            type: string
            enum:
              - eu
              - us
              - global
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                  description: >-
                    The model ID. Use the models endpoint to list models
                    available in your workspace.
                input:
                  description: The input text or full conversation state to process.
                  oneOf:
                    - type: string
                    - type: array
                      items: {}
                    - type: object
                      additionalProperties: true
                instructions:
                  type: string
                  nullable: true
                  description: Instructions added to the model context.
                max_output_tokens:
                  type: integer
                  minimum: 1
                  nullable: true
                  description: The maximum number of output tokens.
                temperature:
                  type: number
                  nullable: true
                  description: Controls response randomness.
                top_p:
                  type: number
                  nullable: true
                  description: Controls nucleus sampling.
                stream:
                  type: boolean
                  nullable: true
                  default: false
                  description: Whether to return native Responses API server sent events.
                tools:
                  type: array
                  description: Function tool definitions. Hosted tools are not supported.
                  items:
                    type: object
                    required:
                      - type
                      - name
                    properties:
                      type:
                        type: string
                        enum:
                          - function
                      name:
                        type: string
                        minLength: 1
                      description:
                        type: string
                        nullable: true
                      parameters:
                        type: object
                        nullable: true
                        additionalProperties: true
                      strict:
                        type: boolean
                        nullable: true
                tool_choice:
                  description: Controls whether the model can call a function.
                  oneOf:
                    - type: string
                      enum:
                        - none
                        - auto
                        - required
                    - type: object
                      required:
                        - type
                        - name
                      properties:
                        type:
                          type: string
                          enum:
                            - function
                        name:
                          type: string
                          minLength: 1
                parallel_tool_calls:
                  type: boolean
                  nullable: true
                  description: Whether the model can return multiple function calls.
                reasoning:
                  type: object
                  description: OpenAI Responses reasoning configuration.
                  additionalProperties: true
                text:
                  type: object
                  description: OpenAI Responses text output configuration.
                  additionalProperties: true
                metadata:
                  type: object
                  nullable: true
                  description: String metadata attached to the request.
                  additionalProperties:
                    type: string
                store:
                  type: boolean
                  nullable: true
                  enum:
                    - false
                  description: >-
                    Responses are not persisted. Omit this field or set it to
                    false.
                background:
                  type: boolean
                  nullable: true
                  enum:
                    - false
                  description: Background responses are not supported.
                include:
                  type: array
                  nullable: true
                  items:
                    type: string
                  description: Additional response fields to include.
                truncation:
                  type: string
                  nullable: true
                  enum:
                    - auto
                    - disabled
                service_tier:
                  type: string
                  nullable: true
                  description: The OpenAI service tier forwarded to the model provider.
            example:
              model: gpt-5-mini
              input: Write a short poem about cats.
              store: false
      responses:
        '200':
          description: Successful response or event stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResponseResponse'
              example:
                id: resp_09e99d1f7f163d10016a678387353481
                object: response
                created_at: 1785168775
                status: completed
                model: gpt-5-mini-2025-08-07
                output:
                  - id: rs_09e99d1f7f163d10016a678387f47881
                    type: reasoning
                    content: []
                    summary: []
                  - id: msg_09e99d1f7f163d10016a67838935a881
                    type: message
                    status: completed
                    role: assistant
                    content:
                      - type: output_text
                        annotations: []
                        logprobs: []
                        text: |-
                          Whiskers sketch moonlight on the sill,
                          paws treading silence, soft and still.
                          Eyes like lanterns, sly and bright,
                          turning midnight into light.
                          A velvet sigh, a sudden purr—
                          the world made small, the heart made her.
                usage:
                  input_tokens: 13
                  input_tokens_details:
                    cached_tokens: 0
                  output_tokens: 154
                  output_tokens_details:
                    reasoning_tokens: 64
                  total_tokens: 167
            text/event-stream:
              schema:
                type: string
                description: Native OpenAI Responses API server sent events.
        '400':
          description: Invalid fields, unsupported features, or an unavailable model.
        '401':
          description: Missing, invalid, or expired API key.
        '403':
          description: API key without the Completion API scope.
        '413':
          description: Request body exceeds 20 MB.
        '429':
          description: Usage or rate limit exceeded.
        '500':
          description: Internal server or upstream provider error.
        default:
          description: Error returned by the upstream model provider.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - message
                      - type
                    properties:
                      message:
                        type: string
                      type:
                        type: string
                      code:
                        type: string
                        nullable: true
                      param:
                        type: string
                        nullable: true
      security:
        - bearerAuth: []
components:
  schemas:
    CreateResponseResponse:
      type: object
      description: A response returned by the OpenAI-compatible Responses endpoint.
      required:
        - id
        - object
        - created_at
        - status
        - model
        - output
      properties:
        id:
          type: string
          description: Unique identifier for the response.
          example: resp_09e99d1f7f163d10016a678387353481
        object:
          type: string
          enum:
            - response
          description: The object type, which is always `response`.
        created_at:
          type: integer
          description: Unix timestamp in seconds when the response was created.
          example: 1785168775
        completed_at:
          type: integer
          nullable: true
          description: Unix timestamp in seconds when the response completed.
          example: 1785168778
        background:
          type: boolean
          enum:
            - false
          description: Langdock does not support background responses.
        status:
          type: string
          enum:
            - completed
            - failed
            - in_progress
            - cancelled
            - queued
            - incomplete
          description: Current response status.
          example: completed
        model:
          type: string
          description: Model used to generate the response.
          example: gpt-5-mini-2025-08-07
        output:
          type: array
          description: Output items generated by the model.
          items:
            oneOf:
              - $ref: '#/components/schemas/ResponseReasoningItem'
              - $ref: '#/components/schemas/ResponseOutputMessage'
              - $ref: '#/components/schemas/ResponseFunctionToolCall'
        output_text:
          type: string
          description: Aggregated text from all `output_text` items.
        error:
          type: object
          nullable: true
          description: Error information when the response failed.
          properties:
            code:
              type: string
              nullable: true
            message:
              type: string
        incomplete_details:
          type: object
          nullable: true
          description: Details explaining why the response is incomplete.
          properties:
            reason:
              type: string
              enum:
                - max_output_tokens
                - content_filter
        instructions:
          type: string
          nullable: true
          description: Instructions used for the response.
        max_output_tokens:
          type: integer
          nullable: true
          description: Maximum number of output tokens configured for the response.
        parallel_tool_calls:
          type: boolean
          description: Whether the model can return multiple function calls.
        reasoning:
          type: object
          nullable: true
          description: Reasoning configuration used for the response.
          additionalProperties: true
        store:
          type: boolean
          enum:
            - false
          description: Langdock Responses are never persisted.
        temperature:
          type: number
          nullable: true
          description: Sampling temperature used for the response.
        text:
          type: object
          nullable: true
          description: Text output configuration used for the response.
          additionalProperties: true
        service_tier:
          type: string
          nullable: true
          description: Service tier used to process the response.
        tool_choice:
          description: Tool choice used for the response.
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
        tools:
          type: array
          description: Function tools available to the model.
          items:
            type: object
            additionalProperties: true
        top_p:
          type: number
          nullable: true
          description: Nucleus sampling value used for the response.
        truncation:
          type: string
          enum:
            - auto
            - disabled
          description: Truncation strategy used for the response.
        usage:
          $ref: '#/components/schemas/ResponseUsage'
        metadata:
          type: object
          nullable: true
          description: Metadata attached to the request.
          additionalProperties:
            type: string
      additionalProperties: true
    ResponseReasoningItem:
      type: object
      description: Reasoning information generated by a reasoning model.
      required:
        - id
        - type
        - summary
      properties:
        id:
          type: string
          example: rs_123
        type:
          type: string
          enum:
            - reasoning
        summary:
          type: array
          items:
            type: object
            additionalProperties: true
        content:
          type: array
          items:
            type: object
            additionalProperties: true
        encrypted_content:
          type: string
          nullable: true
          description: Encrypted reasoning content when requested.
        status:
          type: string
          nullable: true
          enum:
            - in_progress
            - completed
            - incomplete
      additionalProperties: true
    ResponseOutputMessage:
      type: object
      description: A message generated by the model.
      required:
        - id
        - type
        - status
        - role
        - content
      properties:
        id:
          type: string
          example: msg_09e99d1f7f163d10016a67838935a881
        type:
          type: string
          enum:
            - message
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
        role:
          type: string
          enum:
            - assistant
        content:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/ResponseOutputText'
              - $ref: '#/components/schemas/ResponseOutputRefusal'
      additionalProperties: true
    ResponseFunctionToolCall:
      type: object
      description: A function call requested by the model.
      required:
        - id
        - type
        - call_id
        - name
        - arguments
      properties:
        id:
          type: string
          example: fc_123
        type:
          type: string
          enum:
            - function_call
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
        call_id:
          type: string
          example: call_123
        name:
          type: string
          example: lookup_weather
        arguments:
          type: string
          description: JSON-encoded arguments for the function.
          example: '{"city":"Berlin"}'
      additionalProperties: true
    ResponseUsage:
      type: object
      description: Token usage for the response.
      required:
        - input_tokens
        - output_tokens
        - total_tokens
      properties:
        input_tokens:
          type: integer
          example: 13
        input_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
              example: 0
          additionalProperties: true
        output_tokens:
          type: integer
          example: 154
        output_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
              example: 64
          additionalProperties: true
        total_tokens:
          type: integer
          example: 167
      additionalProperties: true
    ResponseOutputText:
      type: object
      description: Text generated by the model.
      required:
        - type
        - text
        - annotations
      properties:
        type:
          type: string
          enum:
            - output_text
        text:
          type: string
          example: |-
            Whiskers sketch moonlight on the sill,
            paws treading silence, soft and still.
        annotations:
          type: array
          items:
            type: object
            additionalProperties: true
        logprobs:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    ResponseOutputRefusal:
      type: object
      description: A refusal returned by the model.
      required:
        - type
        - refusal
      properties:
        type:
          type: string
          enum:
            - refusal
        refusal:
          type: string
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.