Relay: getting started
Create an organisation and an environment, issue a key, point your SDK at Relay, make the first call.
What you need
A Carnegie Relay organisation (early access: we create it for you after a short call), one provider key of your own — Anthropic, OpenAI, or a Google Cloud project with Vertex AI enabled — and an application that already talks to one of those providers.
1. Create an environment
In the console, Environments → New. Name it after what runs through it (prod, staging, data-team). Each environment has its own provider connections, model allow-list, budget and guardrail policy. Start with one.
2. Connect a provider
Environment → Providers → Add. Paste the provider key. It is stored encrypted in Google Cloud Secret Manager under your organisation and decrypted per request; it is never written to logs or traces. For Vertex AI, grant the Relay service account the Vertex AI User role on your project instead of pasting a key.
3. Issue a Relay key
Environment → Keys → New. A Relay key is scoped to exactly one environment and carries a per-minute request limit. Copy it once; only a prefix is shown afterwards.
4. Change the base URL
Relay accepts three wire formats unchanged. Set the base URL and the key, keep everything else.
Anthropic Messages https://relay.carnegieintel.com/v1/models/anthropic
OpenAI Chat Completions https://relay.carnegieintel.com/v1/models/openai
OpenAI Responses https://relay.carnegieintel.com/v1/models/openai
Example (Python, OpenAI SDK):
from openai import OpenAI
client = OpenAI(base_url="https://relay.carnegieintel.com/v1/models/openai", api_key="rly_live_…")
r = client.chat.completions.create(model="gpt-6-astra", messages=[{"role": "user", "content": "ping"}])
Example (Anthropic SDK):
import anthropic
client = anthropic.Anthropic(base_url="https://relay.carnegieintel.com/v1/models/anthropic", api_key="rly_live_…")
5. Read the response headers
Every response carries Relay's verdicts so you can act on them without a dashboard:
X-Relay-Environment: prod
X-Relay-Channel: byok:openai
X-Relay-Guardrail: pass | flag:pii | block:injection
X-Relay-Budget-Used: 1234.56
X-Relay-Budget-Limit: 5000
X-Relay-Request-Id: req_…
6. Tag requests
Add X-Relay-Tags: team=support,project=triage to attribute cost and traffic. Tags appear in traces, dashboards and exports.
What happens on refusal
| Situation | Status | Body error.type |
|---|---|---|
| Model not on the environment's allow-list | 403 | model_not_allowed |
| Hard budget reached | 402 | budget_exceeded |
| Guardrail policy set to block | 422 | guardrail_blocked |
| Key rate limit | 429 | rate_limited |
| No healthy provider | 503 | upstream_unavailable |
Refused requests are not metered.