Skip to Content

Create an OpenAI-format chat completion

POSThttps://api.respan.ai/api/{provider}/v1/chat/completions

Relay an OpenAI-format chat completions payload to one provider and get that provider’s response back byte for byte. Respan authenticates the request, applies your limits , and logs it, but doesn’t translate the request or recompute usage. Respan removes respan_params and merges a literal extra_body object into the body; unknown and provider-only fields are passed through. Streams are relayed frame by frame, and requests time out after 600 seconds.

{provider} is a provider with an OpenAI-format API, such as openai, azure_openai, xai, groq, mistral, deepseek, togetherai, fireworks, or perplexity. A provider without an OpenAI-format API returns 404. A provider with no fixed public endpoint, such as Azure OpenAI, needs the provider URL saved with its key; without it the request returns 400. Anthropic, Google and OpenRouter have their own endpoints.

Upstream, Respan sends only accept, accept-language, content-type, user-agent, and headers that start with x- plus the provider ID, with _ written as - (for example x-azure-openai-). The response includes X-Respan-Log-Id, X-Respan-Upstream-Request-Id, and the provider’s x-ratelimit-* and retry-after headers.

The example uses openai with gpt-6-luna. If you select another provider, use that provider’s model ID and a model supported on Respan credits, or configure your provider key in Settings > Providers.

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Path parameters

Parameter Type Required Description and constraints
provider string Required
The provider ID, such as openai, azure_openai, xai, groq, mistral, deepseek, togetherai, fireworks, or perplexity.
Example: "openai"

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object Required body
Additional properties are allowed
Example: {"model":"gpt-6-luna","messages":[{"role":"user","content":"Reply with exactly ok."}],"max_completion_tokens":32,"reasoning_effort":"none"}
model string Required in parent
The provider’s own model ID.
Example: "gpt-6-luna"
messages array<object> Required in parent
Chat messages in OpenAI format.
messages[] object Array item
Additional properties are allowed
stream boolean Optional
Stream the provider’s response as server-sent events.
respan_params object Optional
Respan parameters such as customer_identifier or metadata. Removed before the request is forwarded.
Additional properties are allowed

OpenAPI request schema

{
  "type": "object",
  "required": [
    "model",
    "messages"
  ],
  "additionalProperties": true,
  "properties": {
    "model": {
      "type": "string",
      "description": "The provider's own model ID.",
      "example": "gpt-6-luna"
    },
    "messages": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      },
      "description": "Chat messages in OpenAI format."
    },
    "stream": {
      "type": "boolean",
      "description": "Stream the provider's response as server-sent events."
    },
    "respan_params": {
      "type": "object",
      "additionalProperties": true,
      "description": "Respan parameters such as `customer_identifier` or `metadata`. Removed before the request is forwarded."
    }
  },
  "example": {
    "model": "gpt-6-luna",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly ok."
      }
    ],
    "max_completion_tokens": 32,
    "reasoning_effort": "none"
  }
}

Responses

200

The provider’s response, unchanged.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

text/event-stream

Field Type Requirement Description and constraints
$ string Body
The provider’s server-sent events, relayed frame by frame.

OpenAPI response schema

{
  "type": "string",
  "description": "The provider's server-sent events, relayed frame by frame."
}

400

No endpoint is known for the provider: save the provider URL with its key. Otherwise, the provider’s own 400.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}
Example
JSON
{ "detail": "No endpoint is known for provider 'azure_openai'. Add an 'api_base' to the integration for this provider, or use the provider's own passthrough endpoint." }

401

No usable key for the provider. The code is activation_required when your organization has no credits and no provider key for the model.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

402

The request’s customer is over their budget.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

403

The API key is missing, invalid or expired.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }

404

The provider isn’t available on this route.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

429

Your Respan key’s rate limit or an API key limit’s block rule, or the provider’s own 429.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Create an OpenAI-format chat completion",
  "operationId": "createProviderChatCompletion",
  "tags": [
    "Provider Gateway"
  ],
  "description": "Relay an OpenAI-format chat completions payload to one provider and get that provider's response back byte for byte. Respan authenticates the request, applies your [limits](/docs/documentation/features/gateway/limits), and logs it, but doesn't translate the request or recompute usage. Respan removes `respan_params` and merges a literal `extra_body` object into the body; unknown and provider-only fields are passed through. Streams are relayed frame by frame, and requests time out after 600 seconds.\n\n`{provider}` is a provider with an OpenAI-format API, such as `openai`, `azure_openai`, `xai`, `groq`, `mistral`, `deepseek`, `togetherai`, `fireworks`, or `perplexity`. A provider without an OpenAI-format API returns `404`. A provider with no fixed public endpoint, such as Azure OpenAI, needs the provider URL saved with its key; without it the request returns `400`. Anthropic, Google and OpenRouter have their own endpoints.\n\nUpstream, Respan sends only `accept`, `accept-language`, `content-type`, `user-agent`, and headers that start with `x-` plus the provider ID, with `_` written as `-` (for example `x-azure-openai-`). The response includes `X-Respan-Log-Id`, `X-Respan-Upstream-Request-Id`, and the provider's `x-ratelimit-*` and `retry-after` headers.\n\nThe example uses `openai` with `gpt-6-luna`. If you select another provider, use that provider's model ID and a model supported on Respan credits, or configure your provider key in Settings > Providers.",
  "parameters": [
    {
      "name": "provider",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "example": "openai"
      },
      "description": "The provider ID, such as `openai`, `azure_openai`, `xai`, `groq`, `mistral`, `deepseek`, `togetherai`, `fireworks`, or `perplexity`."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "model",
            "messages"
          ],
          "additionalProperties": true,
          "properties": {
            "model": {
              "type": "string",
              "description": "The provider's own model ID.",
              "example": "gpt-6-luna"
            },
            "messages": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": true
              },
              "description": "Chat messages in OpenAI format."
            },
            "stream": {
              "type": "boolean",
              "description": "Stream the provider's response as server-sent events."
            },
            "respan_params": {
              "type": "object",
              "additionalProperties": true,
              "description": "Respan parameters such as `customer_identifier` or `metadata`. Removed before the request is forwarded."
            }
          },
          "example": {
            "model": "gpt-6-luna",
            "messages": [
              {
                "role": "user",
                "content": "Reply with exactly ok."
              }
            ],
            "max_completion_tokens": 32,
            "reasoning_effort": "none"
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The provider's response, unchanged.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "text/event-stream": {
          "schema": {
            "type": "string",
            "description": "The provider's server-sent events, relayed frame by frame."
          }
        }
      }
    },
    "400": {
      "description": "No endpoint is known for the provider: save the provider URL with its key. Otherwise, the provider's own `400`.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          },
          "example": {
            "detail": "No endpoint is known for provider 'azure_openai'. Add an 'api_base' to the integration for this provider, or use the provider's own passthrough endpoint."
          }
        }
      }
    },
    "401": {
      "description": "No usable key for the provider. The code is `activation_required` when your organization has no credits and no provider key for the model.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "402": {
      "description": "The request's customer is over their budget.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "404": {
      "description": "The provider isn't available on this route.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "429": {
      "description": "Your Respan key's rate limit or an API key limit's block rule, or the provider's own `429`.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "responses": {
    "InvalidApiKey": {
      "description": "The API key is missing, invalid or expired.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    }
  },
  "securitySchemes": {
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}