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."
          }
        ]
      }
    ]
  }'

Structured JSON output

For non-streaming requests, set text.format.type to json_schema to constrain the response to a JSON Schema:

{
  "model": "gpt-5.2",
  "input": "Return the support ticket priority.",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "ticket_priority",
      "description": "The normalized ticket priority.",
      "schema": {
        "type": "object",
        "properties": {
          "priority": {
            "type": "string",
            "enum": ["low", "medium", "high"]
          }
        },
        "required": ["priority"],
        "additionalProperties": false
      }
    }
  }
}

Hatz validates the schema before invoking the model and validates the returned JSON again before responding. Native JSON Schema output is available only when the selected model and provider support it; unsupported selections return a clear error instead of falling back to unconstrained text. Streaming and request-level tools are not currently supported together with json_schema.

schema must be a JSON Schema object nesting no more than 64 JSON objects or arrays; a deeper schema returns 400 with code invalid_json_schema. That works out to about 31 levels of nested object properties, because each level costs two containers — the subschema and its properties object. max_output_tokens applies to structured requests exactly as it does to plain ones.

Schema references

Your schema must be self-contained. References may only point inside the document you submit: #/$defs/... pointers and whole-document recursion ({"$ref": "#"}) are supported, and $defs is the intended way to reuse a definition.

{
  "type": "object",
  "properties": {
    "ship_from": { "$ref": "#/$defs/address" },
    "ship_to": { "$ref": "#/$defs/address" }
  },
  "required": ["ship_from", "ship_to"],
  "additionalProperties": false,
  "$defs": {
    "address": {
      "type": "object",
      "properties": { "city": { "type": "string" } },
      "required": ["city"],
      "additionalProperties": false
    }
  }
}

Hatz never fetches a reference over the network. A $ref or $dynamicRef pointing outside the submitted document is rejected with 400 and code invalid_json_schema before any model is invoked, so a rejected request is not billed. That covers absolute URLs (https://example.com/schema.json), file:// paths, and relative paths such as common.json — including a relative reference that would resolve against an $id you supplied yourself. Inline the definition or move it into $defs instead.

There is no separate size cap on schema beyond the limits that apply to any request body. Providers enforce their own schema complexity limits, though, so a schema Hatz accepts can still be refused upstream — keep schemas as small as the task allows.

Existing text and json_object formats are unchanged.

Tool Calling Behavior in Responses

input[] may contain chronological system or developer entries. Hatz preserves their effect when the selected model supports the native role and otherwise carries the instruction forward in model context; streaming and non-streaming requests follow the same behavior.

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.