Provider gateway

Sellable product

This capability is granted by an API key scoped to the ai-suite product (product face). See the product reference below.

A unified egress to external AI providers (LLM + embeddings; STT/TTS have their own capabilities) — key custody (BYOK + fleet keys), provider-selection (cost/latency/quality), failover, per-provider circuit-breaker + bulkhead, and per-request usage-metering. Products stop re-implementing provider plumbing. Keys resolved server-side (Infisical/BYOK vault), NEVER in body/DB/logs. Every response carries usage (prompt/completion tokens + provider + cost_cents) — the billed feed consumed by billing-metering (C5) and reconciled into analytics (D4).

• Group: Auth & gateway
• Contract: contracts/provider-gateway/v1/openapi.yaml
• Public base: https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
• Auth: a product API key (vgk_…) issued from the console — Authorization: Bearer vgk_…
• Product face (customer-keyed):
  • https://api.vagarylabs.com/product/v1/ai/chat
• Capability face (internal first-party — NOT customer-keyed):
  • https://api.vagarylabs.com/v1/llm
  • https://api.vagarylabs.com/v1/embeddings

Endpoints

Method	Path	Summary
POST	/v1/llm/chat	Chat/completion via the selected provider (streaming or sync), with failover
POST	/v1/embeddings	Embeddings via the selected provider, with failover + usage
POST	/v1/vision	Vision completion (image + prompt) via the selected vision-capable provider, with failover + usage
GET	/v1/providers	provider health + selection state
GET	/v1/byok/config	List the org's active provider configs — METADATA + masked hint only, NEVER the raw secret
POST	/v1/byok/config	Create/replace (upsert) the org's config for a provider
GET	/v1/byok/config/{provider}	One config's METADATA (masked). 404 if the org has no active config for provider
DELETE	/v1/byok/config/{provider}	Soft-delete (deactivate) the org's config for provider — reversible via POST /v1/byok/config
POST	/v1/byok/config/{provider}/rotate	Rotate the credential on an EXISTING active config. 404 if none exists
POST	/v1/byok/purge	ERASE every stored provider credential the org holds — the BYOK leg of an org-delete cascade. IDEMPOTENT: success is asserted on configs_remaining == 0, so a re-run erasing 0 is still success.
POST	/v1/images/generations	Image generation through the gateway's provider routing (OpenAI-shaped request)
GET	/health	liveness
GET	/metrics	Prometheus

Product face

The external, paying-customer surface served by the edge at /product/v1/* (contracts/provider-gateway/product/v1/openapi.yaml).

Method	Path	Summary
POST	/chat	Chat/completion (managed, metered) — wraps the capability's multi-provider LLM egress

Schemas

Usage

Field	Type	Description
prompt_tokens	integer
completion_tokens	integer
provider_used	string
cost_cents	number
estimated	boolean	false => provider-reported (real) — see D4

LlmRequest

Field	Type	Description
organization_id	string
model	string
messages	array
stream	boolean
tools	array	function-calling tool schemas (OpenAI shape); non-streaming OpenAI surfaces tool_calls. Additive — absent => unchanged completion path
optimization_goal	string
byok	object	bring-your-own-key ref (never a raw key in body)

LlmResponse

Field	Type	Description
content	string
tool_calls	array	function-calling tool calls the model emitted (OpenAI non-streaming); absent/None when the model returned none
usage	object

EmbeddingsRequest

Field	Type	Description
organization_id	string
model	string
input	object
optimization_goal	string	provider-selection goal for the embeddings failover chain (openai, gemini)
byok	object	bring-your-own-key ref (never a raw key in body); resolved server-side per (org, provider)

EmbeddingsResponse

Field	Type	Description
data	array
usage	object

ImageRef

the image to analyze — supply EXACTLY ONE of url or base64 (base64 may include mime_type; the raw bytes are NEVER logged)

Field	Type	Description
url	string	publicly-fetchable image url
base64	string	base64-encoded image bytes (inline)
mime_type	string	e.g. image/png — used with base64; defaults image/jpeg

VisionRequest

Field	Type	Description
organization_id	string
model	string	override the vision model (default gpt-4o / gemini-2.0-flash)
prompt	string	the task prompt — classification/alt-text/OCR instructions supplied by the caller
image	object
optimization_goal	string	provider-selection goal for the vision failover chain (openai, gemini)
byok	object	bring-your-own-key ref (never a raw key in body); resolved server-side per (org, provider)

VisionResponse

Field	Type	Description
content	string	raw vision completion (parse JSON for classification; use directly for alt-text)
usage	object

---

Generated by scripts/gen-capability-docs.py from contracts/provider-gateway/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.