Managing Endpoint Versions

1---
2name: managing-endpoint-versions
3description: >
4  Work safely with endpoint versions — preview a draft in the playground, roll back to an older
5  version, update settings on one version without bumping query history, deactivate a specific
6  version. Use when the user asks "how do I roll back my endpoint", "preview my changes before
7  publishing", "I want to fix v5 without bumping the version", or anything involving the version
8  history. Calls out today's limitations honestly: there is no pointer flip; "rollback" means
9  forking the old query into a new top version.
10---
11 
12# Managing endpoint versions
13 
14This skill is the practical guide to endpoint versioning. It covers the today-workflow, which
15has some sharp edges worth being explicit about.
16 
17## When to use this skill
18 
19- "How do I roll back to v3?"
20- "I want to test changes before they go live"
21- "How do I update the description / `data_freshness_seconds` on a specific version?"
22- "Can I disable v4 without affecting v5?"
23- The user is uncertain whether a query change will cut a new version
24 
25## Versioning model — what to know
26 
27| Behaviour                                                                | Reality                                                                                                              |
28| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
29| Query change                                                             | **Auto-cuts a new version.** Saving any edit to the query creates a new version and bumps the current version number |
30| Settings change (description, `data_freshness_seconds`, materialisation) | Does **not** cut a new version. Updates the targeted version in place                                                |
31| The "current" version                                                    | Always the highest version number — it's not a pointer you can move backwards                                        |
32| Calling without `?version=N`                                             | Runs the **latest** version. So unpinned callers always hit the newest                                               |
33| Disabling the whole endpoint                                             | `endpoint-update` with `is_active: false` (no `version`) takes every version offline at once                         |
34| Disabling a single version                                               | `endpoint-update` with `version` + `is_active: false` retires one version without affecting the others               |
35 
36The model is forward-only. There is no "make v3 the default again" operation today. Practically
37this means "rollback" requires either creating a new top version that re-uses the old query, or
38pinning callers to `?version=N`.
39 
40## Available tools
41 
42| Tool                | Purpose                                                                                         |
43| ------------------- | ----------------------------------------------------------------------------------------------- |
44| `endpoint-versions` | List all versions for an endpoint, latest first                                                 |
45| `endpoint-get`      | Full config; supports `?version=N` to fetch a specific version                                  |
46| `endpoint-update`   | The workhorse — supports `version` body param to target a specific version                      |
47| `endpoint-run`      | Execute a version directly via `?version=N` (without affecting which version other callers hit) |
48 
49## Workflows
50 
51### Previewing a draft before publishing
52 
53There is no "draft" concept in the model. Editing the query commits it as a new version
54immediately. To preview safely:
55 
561. Test the new query first with the `execute-sql` tool (or the SQL editor) — not on the live endpoint
572. When ready, update the endpoint — this creates the new version automatically
583. Use `endpoint-run` with `?version=N` to confirm the new version returns what you expect
594. Old callers still hit the latest version (which is now your new version) — there is no
60   "soft launch"
61 
62If the user needs a true staging endpoint, the only workaround today is a sibling endpoint
63with a `_v2` or `_staging` suffix. Document this honestly — there is no in-product staging path.
64 
65### Rolling back to an older version
66 
67The forward-only model means "rollback" requires forking:
68 
691. `endpoint-versions` to find the version with the good query (say v3)
702. `endpoint-get` with `?version=3` to retrieve that version's query JSON
713. `endpoint-update` with the v3 query as the new query — this **creates a new version** (e.g.
72   v6) with the same query as v3
734. All callers without `?version=N` now hit v6 (== v3's query)
74 
75The old version (v5, the broken one) still exists and is still callable via `?version=5` until
76explicitly deactivated.
77 
78Faster mitigation if you can change every caller: have them pin to `?version=3` until a real
79fix is ready. Lower-impact than cutting a new version.
80 
81### Updating settings on a specific version
82 
83`endpoint-update` accepts a `version` field in the body. When set, settings updates apply to
84that version only — they do not cut a new version. Useful when:
85 
86- Bumping `data_freshness_seconds` on an old version that some callers still pin to
87- Adjusting description on a historical version for clarity
88- Changing materialisation state per version (the materialisation is per-version anyway)
89 
90Important: passing `query` together with `version` is rejected — query changes always cut a new
91top version, never modify history. The version arg only affects settings.
92 
93### Deactivating a single version
94 
95To take v3 out of service while keeping v4 and v5 callable:
96 
97```text
98endpoint-update {name: "...", version: 3, is_active: false}
99```
100 
101This sets `is_active: false` on v3 only. Callers pinned to `?version=3` start getting an error;
102other callers are unaffected.
103 
104To re-enable: same call with `is_active: true`.
105 
106The whole-endpoint `is_active` field (without `version`) is a separate switch — it disables
107every version at once. Use the version-scoped form for surgical takedowns.
108 
109### Pruning unused versions
110 
111Old versions accumulate over time. To find which are dead, call `endpoint-versions` and read each
112version's `last_executed_at`: a version that's null or long stale hasn't been called recently.
113Materialised dead versions are the costly ones — disable their materialisation with
114`endpoint-update` + `version` + `is_materialized: false`, and deactivate with `is_active: false`
115to signal they're retired.
116 
117Confirm with the user before retiring a version: `last_executed_at` counts only personal-API-key
118calls and is recorded only for runs since that tracking was added (so a used version can still
119read null), and a caller may be pinned to `?version=N`. The full audit flow lives in
120`auditing-endpoints`.
121 
122## Example interaction
123 
124```text
125User: "I shipped a broken query last night, v5. How do I roll back?"
126 
127Agent:
128- endpoint-versions <name> → v5 (latest), v4, v3, v2, v1
129- endpoint-get <name> ?version=4 → query JSON for v4
130- "Rolling back means creating v6 with v4's query. v5 stays as a
131   historical version but nobody hits it unless they explicitly
132   pass ?version=5. Sound right?"
133- User confirms
134- endpoint-update <name> {query: <v4 query>} → creates v6
135- endpoint-run <name> ?version=6 to confirm shape
136- "Done. v6 is live with v4's query. Want me to also deactivate v5
137   so it's clear it's defunct?"
138- User: "Yes"
139- endpoint-update <name> {version: 5, is_active: false}
140```
141 
142## Important notes
143 
144- **There is no pointer flip.** "Rolling back" creates a new version. The version number is
145  always going up. If the user is uncomfortable with the resulting history noise, that's a
146  fair concern — surface it honestly.
147- **A query change always creates a new version.** Updating settings on the side does not.
148  If the user wants to fix a typo in v5's description without bumping to v6, use the version
149  param.
150- **Disabling a single version only blocks that version.** It doesn't change which version runs
151  by default — that's always the highest version number.
152- **Materialisation is per-version.** Each version has its own materialised view named
153  `{endpoint_name}_v{version}`. Disabling materialisation on one version doesn't affect others.
154- **Pinning is the safety net — push callers to use it.** Callers that pin to `?version=N` are
155  insulated from query edits; unpinned callers always hit the latest and can be surprised by a new
156  version. Encourage consumers to pin, validate a new version, then bump the pin deliberately.
157- **The CLI manages versions too.** `posthog-cli exp endpoints {pull,push,diff}` lets the user
158  keep endpoint definitions as YAML in version control and review changes before pushing — a
159  cleaner workflow than editing live when query changes need review.
160- **Activating an older version is not yet a product feature.** If the user repeatedly wants this —
161  flip a pointer rather than fork — surface it as a feature gap (and nudge the team via
162  `agent-feedback`). Don't pretend `endpoint-update` does it.
163