API reference

The local gateway provides an initial OpenAI-compatible surface at http://127.0.0.1:7777/v1. Configure MULTIGRID_API_KEY to require bearer authentication for local API clients.

Models

GET /v1/models

Lists available catalog models and route aliases.

Chat Completions

POST /v1/chat/completions

{
  "model": "multigrid/auto",
  "messages": [{"role": "user", "content": "Hello"}],
  "stream": true
}

Streaming uses server-sent events. Route attempts and the model that ultimately answered remain visible in MultiGrid metadata and analytics.

Responses

POST /v1/responses

Supports string or message-array input, developer/system instructions, text and URL-image content, tools, output-token limits, and SSE streaming.

{
  "model": "multigrid/auto",
  "instructions": "Be concise.",
  "input": "Explain local-first software."
}

Embeddings

POST /v1/embeddings

Accepts text, text batches, token IDs and token batches. Embeddings are forwarded only to providers with an OpenAI-compatible embeddings endpoint.

{"model":"openai/text-embedding-3-small","input":["first","second"]}

Hosted account access

A verified hosted user session can inspect its own balance and usage, create or revoke application keys, manage sessions, and—when enabled—start a Stripe-hosted credit checkout through /api/account/*. These account endpoints reject application-key authentication and never return another account’s records. Newly issued mg_live_ secrets are shown once; store them in a secure credential manager. Checkout completion pages do not grant credit; only a verified payment webhook can update the balance. Signed lifecycle events enter a durable retry queue before acknowledgement; failure and expiry events update purchase history without changing credit. Verified refunds and disputes create user-visible review incidents but never silently remove credits. Thresholded failures and incident updates enter a separate durable operations-alert outbox with idempotent email delivery. The administrator-only /api/hosted/payments route exposes queue attempts, errors, pending work, processed events, alert status, incidents, and purchase health.

Compatibility boundaries

Provider-native background Responses, stored-response retrieval, computer-use items, hosted file references and non-OpenAI embedding dialects are not yet supported. Do not assume every provider implements every input type.