List Funnel Revisions
Every save of an AI/HTML funnel's draft (an AI build, an edit in the editor, an import, a restore) is kept as a numbered revision, and none is deleted with age. This route lists them, newest first. After an A/B test is ended, the history starts where the winning version was created. Download any of them with Get Funnel HTML.
GET /v1/funnels/{funnelId}/revisions
:::note Rolling out
Revision history is being enabled workspace by workspace. Until it is enabled for yours, this route answers 404.
:::
Authentication
A signed-in user only: send the OAuth access token the MCP server and the CLI use, as Authorization: Bearer <access token> (see Bearer tokens). Funnels are not available to API keys: a request with x-perspective-api-key is refused with 403.
The user must be able to open the funnel in the app.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
funnelId | path | string | Yes | ID of an AI/HTML funnel. |
version | query | original | variant | No | On a funnel with an A/B test, whose history to list (default original). The two versions have their own revisions. |
limit | query | integer, 1–100 | No | Revisions per page (default 20). |
offset | query | integer, ≥ 0 | No | Revisions to skip (default 0). |
Example request
curl "https://api.perspective.co/v1/funnels/$FUNNEL_ID/revisions?limit=20" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Response
Returns { data: Revision[], meta: { limit, offset } }. A page shorter than limit is the last one.
| Field | Type | Required | Description |
|---|---|---|---|
revision | integer | Yes | The revision's number, counted per version. Pass it to Get Funnel HTML as revision. |
source | string | Yes | What wrote it: manual (the editor), code-editor, ai-funnel (an AI build), mcp, import or restore. |
createdAt | string | Yes | When it was saved (ISO 8601). |
author | object | No | { id, name? } of the user who saved it. Absent when no user did, or the user is gone. |
publishedAt | string | No | When this revision first went live. Absent means unknown, not "never published": publishes before revisions were recorded carry no date. |
isLive | true | No | Present on the revision marked live: the one last published. |
restoredFrom | integer | No | On a restore: the revision it brought back. |
group | string | No | Revisions written by one AI build share it. Collapse them into one entry if you show a history. |
Example response
{
"data": [
{ "revision": 42, "source": "manual", "createdAt": "2026-11-19T10:12:03.000Z", "author": { "id": "64b7…", "name": "Ada Lovelace" } },
{ "revision": 41, "source": "ai-funnel", "createdAt": "2026-11-18T16:40:11.000Z", "group": "build-7f3a", "isLive": true, "publishedAt": "2026-11-18T16:45:00.000Z" }
],
"meta": { "limit": 20, "offset": 0 }
}
Errors
Errors carry a code beside error and status. See Errors.
| Status | code | Meaning |
|---|---|---|
400 | funnelId or a query parameter is invalid. | |
401 | Missing, invalid or expired access token. | |
403 | An API key was sent: funnels need a signed-in user. | |
404 | FUNNEL_NOT_FOUND | No AI/HTML funnel with this ID that you can open. |
404 | EXPERIMENT_ARM_MISSING | version=variant on a funnel without an A/B test. |