OpenAI Responses Compatibility

Use this page when you want strict OpenAI Responses-style behavior from Hatz.

Which endpoint should I use?

If your client expects OpenAI Responses wire format, use /v1/openai/responses.

Base URL

For OpenAI-compatible clients, use this base URL:

https://ai.hatz.ai/v1/openai

Direct HTTP calls can use:

https://ai.hatz.ai/v1/openai/responses

OpenCode Setup

Use OpenCode with the OpenAI provider and point baseURL at the Hatz OpenAI-compat base.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "hatz": {
      "npm": "@ai-sdk/openai",
      "name": "Hatz",
      "options": {
        "baseURL": "https://ai.hatz.ai/v1/openai",
        "apiKey": "${HATZ_API_KEY}"
      },
      "models": {
        "gpt-5.2": { "name": "GPT-5.2" },
        "gpt-4o": { "name": "GPT-4o" },
        "anthropic.claude-haiku-4-5": { "name": "Claude Haiku 4.5" }
      }
    }
  }
}

Notes:

• Use normal model IDs (for example gpt-5.2), not agent_* IDs.
• Model IDs in this page are examples. Query /v1/chat/models and use a model from your tenant's returned list.
• Unknown top-level request fields are ignored for forward compatibility with evolving OpenAI SDK payloads.
• store, include, and reasoning are accepted for OpenAI/OpenCode compatibility.
• previous_response_id and metadata are currently unsupported.

Authentication

This endpoint accepts both authentication methods:

• Authorization: Bearer <your-api-key> (recommended for OpenAI-compatible clients)
• X-API-Key: <your-api-key>

Bearer authentication is supported on the OpenAI- and Anthropic-compatible endpoints only — the rest of the Hatz API requires X-API-Key. See the main authentication docs for details.

Do not send API keys in query strings, request bodies, Basic auth, screenshots, or support messages.

Responses API Example

curl 'https://ai.hatz.ai/v1/openai/responses' \
  -H 'Authorization: Bearer '"$HATZ_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.2",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Write a 2 sentence summary of SOC 2."
          }
        ]
      }
    ]
  }'

Tool Calling Behavior in Responses

The Responses route is client-managed for tools:

1. Model returns a function call output item.
2. Your client executes the tool.
3. Your client sends function result items back in a follow-up /responses request.

The server does not run the Hatz recursive tool harness on this route.

Troubleshooting

If a request fails:

• Confirm the client base URL is https://ai.hatz.ai/v1/openai, not only https://ai.hatz.ai/v1.
• Confirm the API key is sent as Authorization: Bearer <your-api-key> or X-API-Key.
• Query /v1/chat/models with X-API-Key and use a model ID enabled for your tenant.
• Use /v1/chat/completions instead if you need Hatz-native agents, server-side tools, recursive tool calling, or model: "auto".
• Include the X-Request-ID response header, timestamp, status code, sanitized error body, SDK/client version, and model ID when contacting Support.

For status-code triage and a full support evidence packet, see API Troubleshooting.