TYPESAFE_* environment variables across SDKs

TL;DR Four environment variables exist, and both SDKs read all four: TYPESAFE_API_KEY, TYPESAFE_BASE_URL, TYPESAFE_DEFAULT_MODEL, TYPESAFE_LOG_LEVEL. Explicit constructor options always take precedence. TYPESAFE_MODEL, TYPESAFE_ENDPOINT, TYPESAFE_LABEL, and TYPESAFE_PRICE are not SDK environment variables — see Names that are not SDK env vars.

The table

Precedence, stated identically in both SDKs: explicit options take precedence over the environment (raw/docs/sdk__javascript__api__variables__ENV.md; fromCodeOrEnv in raw/github/typesafe-sdk-js/src/env.ts returns fromCode ?? readEnv(envVar)).

The JS SDK also trims values and treats a blank string as unset: process.env[name]?.trim() || undefined (raw/github/typesafe-sdk-js/src/env.ts). No equivalent trimming is documented for Python.

Where each name is defined

The JS type alias EnvVar is typeof ENV[keyof typeof ENV] — i.e. the union of exactly those four string literals (raw/docs/sdk__javascript__api__type-aliases__EnvVar.md). Anything outside that union is not readable through the SDK's readEnv.

Client defaults that are not environment variables

The JS equivalent of the timeout is DEFAULT_TIMEOUT_MS = 10_000 (raw/github/typesafe-sdk-js/src/retry.ts). Neither SDK exposes a timeout environment variable.

Constructor equivalents

Python argument names and docstrings from raw/github/typesafe-sdk-python/src/typesafe_sdk/_core/client/sync/client.py and .../aio/client.py; JS option names from raw/github/typesafe-sdk-js/src/types.ts (TypeSafeClientConfig), which documents the fallbacks as "falls back to TYPESAFE_API_KEY", "falls back to TYPESAFE_BASE_URL, then https://api.typesafe.ai", "falls back to TYPESAFE_DEFAULT_MODEL, then jev-latest", and "falls back to TYPESAFE_LOG_LEVEL, then warn".

Usage

export TYPESAFE_API_KEY="your-key-here"

from typesafe_sdk import Noul, TypeSafeClient

# api_key, base_url and model all come from the environment (or their defaults)
with TypeSafeClient() as client:
    response = client.system_one(
        state="Help! My payouts have been failing for 3 days.",
        questions={"is_urgent": Noul(instructions="Does this convey urgency?")},
    )
    print(response.answers["is_urgent"].noul)

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";

// apiKey, baseURL and defaultModel all come from the environment (or their defaults)
const client = new TypeSafeClient();
const response = await client.systemOne({
  state: { document: "I was charged twice. Please fix this ASAP." },
  questions: {
    category: choice("What is this ticket about?", {
      billing: null,
      technical: null,
      other: null,
    }),
  },
});

console.log(response.answers.category.choice);

(Verbatim from raw/docs/sdk__javascript.md, which introduces it with "Set TYPESAFE_API_KEY in your environment, then create and use the client".)

The direct HTTP equivalent reads the same variable from the shell (raw/docs/introduction__quickstart.md):

curl https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

Names that are not SDK env vars

Four other TYPESAFE_* names appear across raw/. None of them is read by either SDK; do not set them expecting an effect.

Verified by grepping every TYPESAFE_[A-Z_]+ occurrence across raw/ (2026-09-17): only the eight names above appear anywhere, and only the four in The table appear in raw/github/typesafe-sdk-python/src or raw/github/typesafe-sdk-js/src as environment-variable names.

Non-TypeSafe variables that appear alongside them in cookbooks (OPENAI_API_KEY, ANTHROPIC_API_KEY) belong to those vendors' SDKs, not to TypeSafe.

Gotchas

• Cookbook code frequently uses os.environ.get("TYPESAFE_API_KEY", "cache-only") so a keyless kernel replays a JSON cache instead of calling the API. "cache-only" is a sentinel in the cookbook harness, not a real key (raw/docs/cookbooks__citation_check.md).
• Setting TYPESAFE_DEFAULT_MODEL changes which model answers without changing your code; the response's model field reports the version that actually answered, so log it (raw/docs/models.md).
• Setting TYPESAFE_BASE_URL redirects every request, including GET /v1/models. A wrong value typically surfaces as 404 Not Found — see HTTP status codes, rate limits, retry semantics.
• The Python SDK marks authorization, proxy-authorization, x-api-key, api-key, cookie, and set-cookie as secret headers so debug logging does not print your key (raw/github/typesafe-sdk-python/src/typesafe_sdk/_core/constants.py). Turning TYPESAFE_LOG_LEVEL=debug on is therefore safe with respect to the key itself.

Related

• Python SDK: install, clients, system_one() — client construction and system_one()
• JavaScript/TypeScript SDK: install, client, choice/score/noul — client construction and systemOne()
• Python SDK retries, exceptions, constants — the other constants in typesafe_sdk.constants
• HTTP API: POST /v1/systemone and GET /v1/models — what Authorization and the base URL do on the wire
• Models, aliases, pricing, rate limits, context — what jev-latest resolves to
• Quickstart: first call in HTTP, Python, JS — setting the key for the first call

Sources

• raw/docs/sdk__python__api__constants.md (https://docs.typesafe.ai/sdk/python/api/constants)
• raw/docs/sdk__javascript__api__variables__ENV.md (https://docs.typesafe.ai/sdk/javascript/api/variables/ENV)
• raw/docs/sdk__javascript__api__type-aliases__EnvVar.md (https://docs.typesafe.ai/sdk/javascript/api/type-aliases/EnvVar)
• raw/github/typesafe-sdk-python/src/typesafe_sdk/constants.py, .../_core/client/sync/client.py, .../_core/client/aio/client.py, .../_core/constants.py
• raw/github/typesafe-sdk-js/src/env.ts, raw/github/typesafe-sdk-js/src/types.ts, raw/github/typesafe-sdk-js/src/retry.ts
• raw/docs/cookbooks.md and the cookbook pages cited in the table above