Docs / Hosted gateway

Hosted gateway

early access

The hosted gateway serves the same compatibility surfaces as the local edge, operated by ZeroFare over TLS.

Base URL

https://150-136-150-135.sslip.io:8443

During early access the gateway lives on port 8443 alongside the console origin on 443. When a production domain lands (see the roadmap), the base URL moves but the paths and contract stay zerofare.compat/v1.

Authentication

All routes require Authorization: Bearer <api key>. Keys are created in the console (or via the management API), shown exactly once, and stored server-side only as peppered scrypt hashes. Requests without a valid key get a terse, identical 401 regardless of route — nothing can be probed unauthenticated.

Surfaces

Surface	Path	Notes
Chat Completions	`POST /v1/chat/completions`	OpenAI-style; `stream:true` yields SSE.
Responses	`POST /v1/responses`	OpenAI Responses-style.
Messages	`POST /v1/messages`	Anthropic Messages-style.
Models	`GET /v1/models`	List models visible to your key.
Receipts	`GET /v1/decisions/{id}/receipt`	Audit a decision your key made.
Health	`GET /management/v1/healthz`	Unauthenticated liveness.

ZeroFare controls

Every inference call accepts an optional zerofare controls object alongside the standard fields. Controls are validated client-side by the SDK and server-side by the gateway:

const reply = await zf.messages({
  model: "…",
  max_tokens: 256,
  messages: [{ role: "user", content: "hi" }],
  zerofare: { profile: "zerofare.compat/v1" },
});

Streaming

Pass stream:true (or use zf.stream(surface, body) in the SDK) to receive server-sent events. The SDK decodes the stream into an async iterable of { event?, data } and throws on truncated streams:

for await (const evt of zf.stream("chat", { model: "…", messages })) {
  if (evt.data !== "[DONE]") process.stdout.write(JSON.stringify(evt.data));
}

Errors

Errors are structured objects with a machine-readable profile — never bare strings:

{
  "error": {
    "code": "ADMISSION_DENIED",
    "message": "fair-share admission queue full",
    "retryable": true,
    "profile": "zerofare.compat/v1"
  }
}

The SDK raises these as typed ZeroFareErrors with the status code attached. Honor retryable; admission denials are transient by design.

Receipts

Every request produces a decision record. Fetch the receipt afterwards to audit admission, routing, and finalization:

const proof = await zf.receipt(decisionId);

Early-access limits

Fair admission: capacity is shared across early-access tenants; under load a request can be admitted-queued (ADMISSION_DENIED, retryable).
Tenant isolation: keys never see other tenants' data; isolation is enforced server-side and covered by a dedicated test suite.
Full provider dispatch on the hosted path is Phase 2 — see the roadmap for current state.