Model Compatibility, Limits, and Usage

Use this appendix when you are integrating with Hatz model APIs and need to understand model IDs, compatibility routes, Auto routing, aliases, token counting, rate limits, and what to include in support requests.

Model IDs

Use /v1/chat/models to retrieve the live model IDs available to your API key.

curl 'https://ai.hatz.ai/v1/chat/models' \
  -H "X-API-Key: $HATZ_API_KEY"

For routes that require a concrete model, the returned name value is the model ID to send in API requests. /v1/chat/completions also supports auto for Auto routing and agent-{id} for agent-backed requests. Model availability can vary by tenant, role, MSP policy, product rollout, provider availability, and package or usage state. Do not hard-code availability assumptions from examples.

Compatibility Routes

Hatz exposes multiple LLM routes:

Use a compatibility route when your client expects that provider's request and response shape. Use /v1/chat/completions for Hatz-native chat, agents, server-side tools, and recursive tool calling.

Auto Routing

On /v1/chat/completions, pass "model": "auto" to let Hatz choose a model for the request. Auto routing respects the user's saved Auto mode and organization policy. If strict reproducibility matters, pin a specific model ID from /v1/chat/models.

There is currently no per-request Auto-mode override on the API. Update the account's default Auto mode in Hatz AI Preferences when you need to change how aggressively Auto scales up.

Anthropic Aliases

The Anthropic-compatible route accepts Hatz model IDs and supported Claude-family aliases such as sonnet, opus, and haiku. It also accepts native Claude-style IDs that map to enabled Hatz models for Claude Desktop compatibility. Aliases resolve to the current enabled model in that family unless the user has configured custom Anthropic gateway model mappings in Hatz AI Preferences.

Use /v1/chat/models when you need the exact enabled model IDs for your tenant. Aliases are convenience handles and can change as the current family model changes.

Tokens and Context

Tokens are the input and output units processed by the model. Context can include messages, files, system instructions, tool schemas, tool results, and prior conversation history.

The Anthropic-compatible count_tokens endpoint is intended for client-side preflight checks. Final usage accounting is recorded from the final model response, not from preflight estimates.

Credits and Multipliers

Hatz credits depend on model rates, input and output size, files, tools, retries, generated outputs, and workflow or agent structure. Model multipliers are directional comparisons for model cost intensity; they are useful for choosing models, but they are not exact per-request quotes.

For API usage review, use the Usage API to inspect usage by model or other available dimensions.

Rate Limits and Limit Errors

Limit behavior can come from multiple sources:

• Tenant or role credit limits.
• Model or package restrictions.
• API key or account policy.
• Request size or context limits.
• Request concurrency or retry state.
• Upstream provider throttling or provider availability.

When a limit is expected, use the returned status and error detail to decide whether to retry, reduce request size, switch models, wait for the usage period to reset, or ask an admin to review package, role, or tenant policy.

Common Support Evidence

For API model, token, rate-limit, timeout, or response-quality support, include:

• Endpoint and compatibility route.
• Model ID or alias sent.
• Timestamp and timezone.
• Request ID, job ID, workflow job ID, or other correlation ID when available.
• HTTP status code and sanitized response body.
• Whether streaming was enabled.
• Whether tools, files, images, or large context were involved.
• Expected behavior and actual behavior.
• Whether the issue reproduces with the same payload after removing secrets and customer-sensitive data.
• Business impact, urgency, and workaround.

Do not send raw API keys, bearer tokens, private secrets, full sensitive prompts, or customer data that is not needed for diagnosis.