/managing-endpoint-versions

name: managing-endpoint-versions
description: >
  Work safely with endpoint versions — preview a draft in the playground, roll back to an older
  version, update settings on one version without bumping query history, deactivate a specific
  version. Use when the user asks "how do I roll back my endpoint", "preview my changes before
  publishing", "I want to fix v5 without bumping the version", or anything involving the version
  history. Calls out today's limitations honestly: there is no pointer flip; "rollback" means
  forking the old query into a new top version.

Managing endpoint versions

This skill is the practical guide to endpoint versioning. It covers the today-workflow, which has some sharp edges worth being explicit about.

When to use this skill

• "How do I roll back to v3?"
• "I want to test changes before they go live"
• "How do I update the description / `data_freshness_seconds` on a specific version?"
• "Can I disable v4 without affecting v5?"
• The user is uncertain whether a query change will cut a new version

Versioning model — what to know

| Behaviour | Reality | | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | Query change | **Auto-cuts a new version.** Saving any edit to the query creates a new version and bumps the current version number | | Settings change (description, `data_freshness_seconds`, materialisation) | Does **not** cut a new version. Updates the targeted version in place | | The "current" version | Always the highest version number — it's not a pointer you can move backwards | | Calling without `?version=N` | Runs the **latest** version. So unpinned callers always hit the newest | | Disabling the whole endpoint | `endpoint-update` with `is_active: false` (no `version`) takes every version offline at once | | Disabling a single version | `endpoint-update` with `version` + `is_active: false` retires one version without affecting the others |

The model is forward-only. There is no "make v3 the default again" operation today. Practically this means "rollback" requires either creating a new top version that re-uses the old query, or pinning callers to `?version=N`.

Available tools

| Tool | Purpose | | ------------------- | ----------------------------------------------------------------------------------------------- | | `endpoint-versions` | List all versions for an endpoint, latest first | | `endpoint-get` | Full config; supports `?version=N` to fetch a specific version | | `endpoint-update` | The workhorse — supports `version` body param to target a specific version | | `endpoint-run` | Execute a version directly via `?version=N` (without affecting which version other callers hit) |

Workflows

Previewing a draft before publishing

There is no "draft" concept in the model. Editing the query commits it as a new version immediately. To preview safely:

1. Test the new query first with the `execute-sql` tool (or the SQL editor) — not on the live endpoint 2. When ready, update the endpoint — this creates the new version automatically 3. Use `endpoint-run` with `?version=N` to confirm the new version returns what you expect 4. Old callers still hit the latest version (which is now your new version) — there is no "soft launch"

If the user needs a true staging endpoint, the only workaround today is a sibling endpoint with a `_v2` or `_staging` suffix. Document this honestly — there is no in-product staging path.

Rolling back to an older version

The forward-only model means "rollback" requires forking:

1. `endpoint-versions` to find the version with the good query (say v3) 2. `endpoint-get` with `?version=3` to retrieve that version's query JSON 3. `endpoint-update` with the v3 query as the new query — this **creates a new version** (e.g. v6) with the same query as v3 4. All callers without `?version=N` now hit v6 (== v3's query)

The old version (v5, the broken one) still exists and is still callable via `?version=5` until explicitly deactivated.

Faster mitigation if you can change every caller: have them pin to `?version=3` until a real fix is ready. Lower-impact than cutting a new version.

Updating settings on a specific version

`endpoint-update` accepts a `version` field in the body. When set, settings updates apply to that version only — they do not cut a new version. Useful when:

• Bumping `data_freshness_seconds` on an old version that some callers still pin to
• Adjusting description on a historical version for clarity
• Changing materialisation state per version (the materialisation is per-version anyway)

Important: passing `query` together with `version` is rejected — query changes always cut a new top version, never modify history. The version arg only affects settings.

Deactivating a single version

To take v3 out of service while keeping v4 and v5 callable:

endpoint-update {name: "...", version: 3, is_active: false}

This sets `is_active: false` on v3 only. Callers pinned to `?version=3` start getting an error; other callers are unaffected.