Developer documentation

API reference

OpenAI-compatible — point your SDK at our base URL and keep your code. Add a header to pin data residency, declare PHI, or pick a model tier.

https://api.phi-cloud.com/v1Get started

Per-request residency headersPHI-aware routingDrop-in OpenAI SDK

Quickstart

From zero to a first call in under a minute.

Point your existing OpenAI SDK at https://api.phi-cloud.com/v1, pass your phi_live_ key, and add X-Region to pin where the request is processed. That is the whole integration.

POST/v1/chat/completions

curl https://api.phi-cloud.com/v1/chat/completions \  -H "Authorization: Bearer phi_live_…" \  -H "X-PHI: false" \  -H "X-Region: CH" \  -H "Content-Type: application/json" \  -d '{    "model": "auto",    "messages": [      {"role": "user", "content": "Hello"}    ]  }'

No code? Use the hosted chat

Prefer to talk to it directly? /dashboard/chat is the same router behind a multi-turn chat UI — pick a region, pick a model, send messages. Conversation history stays in your browser; the gateway stores nothing.

Heads up

Live keys are prefixed phi_live_. Keep them server-side — never ship a key to a browser or mobile client.

Auth

Authentication

Every request carries your secret API key as a bearer token in the Authorization header. Keys are stateless and verified without a database round-trip.

Authorization: Bearer phi_live_…

Authorizationstringrequired

Bearer token. Issue and rotate keys in the dashboard.

Routing

Request headers

Three optional request headers steer the router. Omit them to fall back to your account defaults.

X-PHItrue | falseoptional

Declare the payload class. Set true when the request contains protected health information — the router then restricts to PHI-eligible, in-jurisdiction providers. Defaults to false.

X-RegionCH | EU | US | UK | WORLDoptional

Override the routing region to pin where the request is processed. Defaults to WORLD.

X-Model-Tierfast | baseline | thinkingoptional

Soft preference — the router picks the cheapest eligible model within the tier you request.

Endpoint

Chat completions

POST/v1/chat/completions — Standard OpenAI chat schema. Set model to auto to let the router choose, or pin a specific model id from /v1/models.

modelstringrequired

Model id, or auto to let the router pick the cheapest eligible model for your region and tier.

messagesarrayrequired

The conversation, as OpenAI-style { role, content } objects.

temperaturenumberoptional

Sampling temperature. Passed through to the upstream model.

max_tokensnumberoptional

Maximum number of tokens to generate in the completion.

POST/v1/chat/completions

curl https://api.phi-cloud.com/v1/chat/completions \  -H "Authorization: Bearer phi_live_…" \  -H "X-PHI: false" \  -H "X-Region: CH" \  -H "Content-Type: application/json" \  -d '{    "model": "auto",    "messages": [      {"role": "system", "content": "You are a careful assistant."},      {"role": "user", "content": "Hello"}    ]  }'

Endpoint

Embeddings

POST/v1/embeddings — Generate embedding vectors for one or more inputs. The same residency rules and X-PHI gate apply.

modelstringrequired

Embedding model id, or auto.

inputstring | string[]required

A single string or an array of strings to embed.

POST/v1/embeddings

curl https://api.phi-cloud.com/v1/embeddings \  -H "Authorization: Bearer phi_live_…" \  -H "X-PHI: false" \  -H "Content-Type: application/json" \  -d '{    "model": "auto",    "input": ["text to embed"]  }'

Endpoint

List models

GET/v1/models — Returns the catalog visible to your account, filtered by jurisdiction (honours X-Region / X-PHI) so you only see routes that would succeed. Each entry carries pricing, region, and PHI eligibility — use it to render a model picker.

GET/v1/models

curl https://api.phi-cloud.com/v1/models \  -H "Authorization: Bearer phi_live_…" \  -H "X-Region: CH"

Residency

Response headers

Every 200 response echoes the routing decision so you can audit residency and cost per request.

x-phi-routedmodel/region/class

The resolved route: modelId/regionCode/dataClass — authoritative record of what served the request.

x-phi-tierphi | non_phi

Whether the chosen route was PHI-eligible.

x-phi-attemptsnumber

How many routes were tried before one succeeded (fail-over stays inside the PHI tier for PHI requests).

x-phi-cost-micronumber

Metered cost of the request, in micro-units.

x-request-iduuid

Unique id for the request — quote it in support tickets.

< HTTP/2 200< x-phi-routed: gpt-4o-mini/CH/general< x-phi-tier: non_phi< x-phi-attempts: 1< x-phi-cost-micro: 4200< x-request-id: 9f1c…

Routing

Models & routing

Two tiers, fallback non-PHI > PHI. PHI requests are filtered to PHI-eligible routes and never spill to a non-PHI provider. See /network for the live region map and /vendors for the full provider & model registry.

non-PHI tierdefault

Self-hosted Medishift worker. Default for every task in every region except CHINA. $0 per token. Not PHI-eligible.

PHI tierX-PHI: true

Infomaniak (CH) only, for now. The sole PHI-eligible provider today — PHI is pinned to Switzerland and processed under Swiss law.

Honest status

Anthropic, OpenAI, Mistral and Google are non-PHI today and become PHI-eligible per-region as each BAA / DPA lands.

Reference

Errors

Errors return a JSON body of the shape { "error": { "code", "message" } } with a matching HTTP status.

401missing_authorization

No Bearer token on the request.

401invalid_api_key

The token is invalid or revoked.

403phi_blocked

X-PHI: true but no PHI-eligible route exists for the requested region. This is correct behaviour — the gateway refuses to silently cross a border.

422no_route

No route serves this task / region / data-class combination.

400invalid_json

The request body was not valid JSON, or failed schema validation.

502upstream_error

Every candidate route failed at the upstream provider.

HTTP/2 403content-type: application/json{  "error": {    "code": "phi_blocked",    "message": "No PHI-eligible route for region=US. PHI is pinned to CH today."  }}

403 phi_blocked is by design

When X-PHI: true is set in a region with no eligible provider, the gateway refuses the request rather than failing over to a non-PHI route. Pin X-Region: CH or use the non-PHI tier.

Keep going

Next steps

Where to go from here once your first call is working.

/networkpage

Live region map and which providers are PHI-eligible where.

/compliancepage

nFADP / GDPR posture, sub-processors, and the audit trail you ship by default.

/pricingpage

Per-token rates, the 8% gateway margin, and the $0 non-PHI tier.

/platformpage

Architecture, statelessness contract, and how routing decisions are made.

Start building See pricing