API reference overview

The Arbitex Gateway API exposes an OpenAI-compatible endpoint that sits in front of any AI provider. You send requests in the standard OpenAI chat completions format, and the gateway handles provider routing, DLP inspection, policy enforcement, and audit logging transparently before forwarding to the upstream provider.

---

Base URL

All API requests go to:

https://api.arbitex.ai/v1

The /v1 prefix matches the OpenAI API namespace, so any SDK or tool that supports a configurable base URL works without modification.

---

Authentication

Every request must include a valid Arbitex API key. Two header formats are accepted:

Authorization: Bearer arb_live_your-api-key-here

X-API-Key: arb_live_your-api-key-here

Both are equivalent. Use Authorization: Bearer if you are configuring the OpenAI SDK — it passes credentials in this format by default. Use X-API-Key if you are calling the API directly and want to keep the Authorization header available for application-level tokens.

API keys are scoped to an organization and carry the user identity of the key owner. Policy Engine rules that target specific users or groups apply based on this identity. You can create service accounts and issue keys to them from Settings > API Keys in the admin portal.

Keys do not expire by default. You can set a hard expiry date per key, or rotate a key manually by deleting it and issuing a new one.

---

Rate limiting

The gateway enforces rate limits at the organization level and, optionally, at the user level. The following headers appear on every response:

Header	Type	Description
X-RateLimit-Limit	integer	The maximum number of requests permitted in the current window
X-RateLimit-Remaining	integer	Requests remaining in the current window
X-RateLimit-Reset	integer	Unix timestamp (seconds) when the current window resets

When you exceed the rate limit, the gateway returns a 429 status code with a quota_exceeded error code. The X-RateLimit-Reset header tells you when the window resets.

Limits are set per organization. Contact your Arbitex account representative to adjust them. User-level limits, if configured, share the same header names and follow the same semantics — the headers reflect whichever limit is most constraining (org-level or user-level) for the current request.

---

Policy response headers

After policy evaluation, the gateway attaches decision metadata to every response. These headers tell your application what the Policy Engine decided.

Header	Values	Description
X-Policy-Action	ALLOW, BLOCK, CANCEL, REDACT, ROUTE_TO	The terminal action taken by the Policy Engine. Present on all responses.
X-Matched-Rule	rule ID string, or absent	The ID of the specific rule that matched. Omitted when X-Policy-Action is ALLOW — to avoid leaking policy structure to callers.

If X-Policy-Action is ALLOW, neither the pack nor the rule ID is disclosed. If the action is anything else, X-Matched-Rule is present so your application can programmatically detect policy blocks and handle them appropriately.

---

Error codes

The gateway uses standard HTTP status codes alongside a JSON error body with a code field for machine-readable classification.

429 — quota_exceeded

Returned when the request exceeds your organization’s rate limit or token budget.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Rate limit exceeded. Retry after 2026-03-08T14:33:00Z.",
    "type": "rate_limit_error"
  }
}

Inspect X-RateLimit-Reset to determine when to retry. Implement exponential backoff; do not retry immediately in a tight loop.

403 — policy_block

Returned when the Policy Engine’s terminal action is BLOCK. The optional policy message (configured per rule) appears in the message field.

{
  "error": {
    "code": "policy_block",
    "message": "OpenAI access is not permitted for your group.",
    "type": "policy_error",
    "rule_id": "rule_01HZ_BLOCK_OPENAI"
  }
}

Your application should not retry a policy_block — the same request will receive the same response until the policy changes. Log the rule_id for audit purposes; it matches the matched_rule_id field in the audit log entry for this request.

503 — provider_unavailable

Returned when all configured providers in the routing chain are unavailable and failover is exhausted.

{
  "error": {
    "code": "provider_unavailable",
    "message": "All configured providers are currently unavailable.",
    "type": "provider_error"
  }
}

This is a transient error. Retry with exponential backoff. If you have configured a failover chain, this error means all providers in the chain failed — review your provider configuration in Settings > Providers.

Other error codes

Code	HTTP status	Description
invalid_api_key	401	API key not found, revoked, or malformed
model_not_found	404	The requested provider/model-id is not recognized or is not available for your organization
context_length_exceeded	400	The request exceeds the model’s context window
invalid_request	400	Malformed request body — missing required fields or invalid types

---

OpenAI API compatibility

The Arbitex Gateway API is a superset of the OpenAI Chat Completions API. Any client, SDK, or tool that targets the OpenAI /v1/chat/completions endpoint works against the gateway without code changes — you change only the base URL and API key.

The model field uses the format provider/model-id to specify both the provider and the model explicitly:

"model": "anthropic/claude-sonnet-4-20250514"
"model": "openai/gpt-4o"
"model": "google/gemini-2.0-flash"

If you omit the provider prefix and supply only a model ID, the gateway attempts to resolve the model against your configured provider list. This is supported for compatibility with existing integrations, but the provider/model-id format is preferred because it is unambiguous.

Arbitex extends the standard OpenAI response format in two ways:

1. Policy headers — X-Policy-Action and X-Matched-Rule on every response (see Policy response headers above)
2. DLP streaming events — dlp_correction and output_blocked event types in SSE streams (see Chat completions)

All other response fields are identical to the OpenAI format. OpenAI SDK response parsing requires no modification.

---

Next steps

• Chat completions — full reference for POST /v1/chat/completions, including streaming, DLP events, and request/response field details
• Policy Engine overview — how the gateway evaluates requests against your policy chain
• DLP Overview — how the 3-tier DLP pipeline inspects requests and responses
• Audit log — what gets logged for every gateway request