usestrix/strix · error · SpecParseError

POSTMAN_API_KEY is not set. Export a Postman API key (PMAK-…

Error message

POSTMAN_API_KEY is not set. Export a Postman API key (PMAK-…) to fetch from the Postman API, or pass a local collection file instead.

What it means

SpecParseError raised by _postman_api_json when fetching a Postman resource by UID but no API key was supplied (empty POSTMAN_API_KEY). The Postman API requires an X-Api-Key header (PMAK-…); without it the request is never attempted.

Source

Thrown at strix/utils/api_spec.py:245

    if spec_format == "swagger":
        return _swagger_base_urls(raw)
    if spec_format == "postman":
        return _postman_base_urls(raw, extra_variables)
    raise SpecParseError("File is not a recognized OpenAPI, Swagger, or Postman spec")


POSTMAN_API_BASE = "https://api.getpostman.com"
_POSTMAN_FETCH_TIMEOUT = 30


def _postman_api_json(url: str, api_key: str, label: str) -> dict[str, Any]:
    """GET a Postman API resource and return the parsed JSON payload.

    Raises :class:`SpecParseError` with an actionable message on auth, network,
    or shape errors.
    """
    if not api_key:
        raise SpecParseError(
            "POSTMAN_API_KEY is not set. Export a Postman API key (PMAK-…) to "
            "fetch from the Postman API, or pass a local collection file instead.",
        )
    try:
        response = requests.get(
            url,
            headers={"X-Api-Key": api_key, "Accept": "application/json"},
            timeout=_POSTMAN_FETCH_TIMEOUT,
        )
    except requests.RequestException as exc:
        raise SpecParseError(f"Failed to reach the Postman API: {exc}") from exc

    if response.status_code == 401:
        raise SpecParseError("Postman API rejected the key (401). Check POSTMAN_API_KEY.")
    if response.status_code == 404:
        raise SpecParseError(
            f"Postman {label} not found (404). Check the id and that the key can access it.",
        )

View on GitHub (pinned to 8551339130)

Solutions

export POSTMAN_API_KEY=PMAK-xxxx (Settings → API Keys in Postman) and re-run
Pass the key explicitly if the CLI supports it, or mount it into the container env
Alternative: skip the API entirely and export the collection JSON, then pass the local file

Example fix

# before
strix --api-spec postman:12345-abcdef  # no key in env

# after
export POSTMAN_API_KEY="PMAK-xxxxxxxx"
strix --api-spec postman:12345-abcdef

Defensive patterns

Strategy: validation

Validate before calling

import os

if spec.startswith("postman") and not (os.environ.get("POSTMAN_API_KEY") or "").startswith("PMAK-"):
    raise RuntimeError("export POSTMAN_API_KEY (PMAK-…) or pass a local collection file")

Type guard

def has_postman_key() -> bool:
    import os
    return os.environ.get("POSTMAN_API_KEY", "").startswith("PMAK-")

Try / catch

try:
    coll = fetch_postman_collection(uid, api_key)
except SpecParseError as e:
    if "POSTMAN_API_KEY is not set" in str(e):
        prompt for the key or switch to a local export — do not retry unchanged

Prevention

Check the env var at job start, not at call time
For Docker runs, pass -e POSTMAN_API_KEY or mount the secret
Keep a local collection export as a no-network fallback

When it happens

Trigger: Passing a postman:// or collection-UID style spec target without exporting POSTMAN_API_KEY; the variable set to an empty string in the shell or Docker env; the key present in a .env file that was never loaded.

Common situations: CI job that omits the secret; key defined for the interactive shell but not passed to the Docker sandbox; typo in the variable name (POSTMAN_KEY, POSTMAN_APIKEY).

Related errors

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/f28716bf3a7ce6bd. Report an issue: GitHub.