Connect an app in two changes

Base URL and key

Base URL

The address of your TerraFlow plane, https://<your-terraflow-host>. The console's Connect screen shows yours, with snippets ready to copy. OpenAI SDKs take the base URL with /v1 on the end; Anthropic SDKs take the host alone.

API key

Starts with tf_. Send it the way your SDK already does: Authorization: Bearer tf_… or x-api-key: tf_…. Both are accepted on every /v1 endpoint.

Key storage

TerraFlow stores only a SHA-256 hash of the key; the console shows its first characters, never the key. An admin can rotate it, which shows the new key once and revokes the old one at once.

Choosing a workload

A workload is one AI use case with its own signed contract: the data it may carry, the models it may use, its budgets and whether answers need human approval. Every request runs under exactly one.

1. X-TerraFlow-Workload: <workload-id> chooses it. An unknown id is refused with UNKNOWN_WORKLOAD (403).
2. Without that header, a model that is a workload id (for example starter-assistant) chooses it.
3. Otherwise your default workload applies.

Pinning a model. A model that is a model's TerraFlow id (such as anthropic-sonnet) or its vendor id (such as claude-sonnet-5-5) pins that model. The request is still checked against the rules; if that model is not allowed, the request is refused with the reason, never silently sent elsewhere. Any other value, including auto, lets TerraFlow choose within the contract. Read x-terraflow-capability to see which model answered.

OpenAI-compatible: chat completions

POST /v1/chat/completions accepts the Chat Completions body: messages, stream, tools, response_format, max_tokens or max_completion_tokens, temperature, user.

curl

curl https://<your-terraflow-host>/v1/chat/completions \
  -H "Authorization: Bearer $TERRAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-TerraFlow-Workload: starter-assistant" \
  -H "X-TerraFlow-Data-Class: internal" \
  -H "Idempotency-Key: 6f1c2a9e-ticket-4821" \
  -d '{"model": "auto",
       "messages": [{"role": "user", "content": "In two sentences, what does an AI control plane do?"}]}'

Python · openai

# pip install openai
import os
from openai import OpenAI

client = OpenAI(base_url="https://<your-terraflow-host>/v1",
                api_key=os.environ["TERRAFLOW_API_KEY"])          # starts with tf_
reply = client.chat.completions.create(
    model="starter-assistant",   # a TerraFlow workload, not a vendor model: TerraFlow picks the route
    messages=[{"role": "user", "content": "In two sentences, what does an AI control plane do?"}],
    extra_headers={"X-TerraFlow-Data-Class": "internal"},
)
print(reply.choices[0].message.content)

Every governed answer also carries a terraflow block in its body: request_id, outcome, reason_code, capability_id, cost_usd, savings_usd and review_id.

Anthropic-compatible: messages

POST /v1/messages accepts the Messages body: system, messages, tools, stream, max_tokens, temperature, metadata.user_id.

curl

curl https://<your-terraflow-host>/v1/messages \
  -H "x-api-key: $TERRAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-TerraFlow-Data-Class: internal" \
  -d '{"model": "starter-assistant", "max_tokens": 300,
       "messages": [{"role": "user", "content": "In two sentences, what does an AI control plane do?"}]}'

Python · anthropic

# pip install anthropic
import os
import anthropic

client = anthropic.Anthropic(base_url="https://<your-terraflow-host>",   # host only, no /v1
                             api_key=os.environ["TERRAFLOW_API_KEY"])
reply = client.messages.create(
    model="starter-assistant",
    max_tokens=300,
    messages=[{"role": "user", "content": "In two sentences, what does an AI control plane do?"}],
    extra_headers={"X-TerraFlow-Data-Class": "internal"},
)
print(reply.content[0].text)

All endpoints

Headers

Request headers (all optional)

On /v1/chat/completions and /v1/messages. An invalid value is refused with a 400 before anything is governed, so a typo can never silently lower a protection.

Response headers

What a governed refusal looks like

A refusal is an ordinary HTTP error in the shape your SDK expects, with TerraFlow's reason code inside, so your SDK raises its usual exception. A request refused by its rules never reaches a model, and the refusal is still recorded in the audit record.

/v1/chat/completions · 403

{"error": {"type": "permission_error", "code": "DATA_CLASS_NOT_PERMITTED",
           "message": "TerraFlow denied: DATA_CLASS_NOT_PERMITTED",
           "terraflow": {"request_id": "req_01m3j…", "reason_code": "DATA_CLASS_NOT_PERMITTED"}}}

/v1/messages · 403

{"type": "error",
 "error": {"type": "permission_error", "message": "TerraFlow denied: DATA_CLASS_NOT_PERMITTED"},
 "terraflow": {"request_id": "req_01m3j…", "reason_code": "DATA_CLASS_NOT_PERMITTED"}}

The same code is in the x-terraflow-reason header. Common codes:

Held for approval. When a workload's rules require a person to approve an answer, the outcome is HELD with reason REVIEW_PENDING. On /v1/chat/completions and /v1/messages it is a 200 whose answer is a placeholder naming the review id (so SDKs do not break); on /v1/invocations it is a 202. Fetch the released answer with GET /v1/reviews/{id}.

Every code, its status and the action to take is in the reason-code reference, generated from docs/public/reason-codes.yaml and docs/public/error-codes.yaml, which the build checks against the code.

Idempotency and retry-later

• Same key, same body, within 24 hours: the original outcome is returned without running or charging again, marked x-terraflow-idempotent-replay: true.
• Same key, different body: IDEMPOTENCY_CONFLICT (409).
• Answer no longer available to replay: IDEMPOTENCY_REPLAY_NO_CONTENT (409), with the original request id. A refused or failed original replays as itself.
• retry-after (seconds) is set on refusals that a later retry can pass: rate limits, a shed queue, a spend ceiling.
• x-should-retry: false is set when an automatic retry cannot succeed soon: a spent budget, an exhausted deadline.

Streaming

Set stream: true as usual; both channels stream server-sent events in their own format.

• Held back, then streamed when the workload needs the whole answer checked first: a customer or public audience, consequence tier T2 or above, an output schema, content rules, or human review. Every header is sent first.
• Passed straight through otherwise. The answer is checked once complete; the outcome and cost are in the console and the request's audit events.
• A request refused before it starts is an ordinary error response, not a stream.

Limits

Not supported

• A public /v1/embeddings endpoint, the OpenAI Responses and Assistants APIs, audio, image generation and files. Use Chat Completions or Messages.
• Images, audio and files inside a prompt cannot be scanned, so they are treated as restricted data with every sensitive type; a workload that does not accept that refuses them.
• TerraFlow never runs tools: tool calls come back to your code unexecuted, after the same sensitive-data checks as text.

Source of truth: terraflow/gateway/ (openai_router.py, anthropic_router.py, native_router.py, auth.py) and terraflow/core/reasons.py.