> ## 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.

<Info>
  **Using the API through a dedicated deployment?** Replace `api.langdock.com` with your deployment's base URL: **`<deployment-url>/api/public`**
</Info>

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.

<Info>
  To use the API, 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. Personal keys only include the Completion API scope.
</Info>

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).

## Supported fields

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 **60,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 extra usage budget 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"

````