List the revisions of an edit

list_timeline_revisionsGET/v1/projects/{projectId}/timeline/revisionsBeta

Lists the revisions of an edit that can be restored, newest first, with who wrote each one and what it did.

Beta. This endpoint is supported and can gain new fields. If a change would break your code, we tell you before it takes effect and list it in the changelog.

About

Call it to find a revision to go back to with restore_timeline (POST /v1/projects/{projectId}/timeline/restore). Only the recent revisions of an edit are kept, for a limited time: a revision that is not in this list cannot be restored. The list is newest first and paged with cursor and limit.

Example use

A reviewer who dislikes the last round of changes lists the revisions of the edit, finds the one from before them by who wrote it and what it did, and keeps its number for restore_timeline (POST /v1/projects/{projectId}/timeline/restore).

Endpoint

Code

GET https://api.gpt-video.com/v1/projects/{projectId}/timeline/revisions

Scope clips:read.
Rate limit 120 requests a minute for each key and 240 for each account, shared by every read call. See rate limits.
No Idempotency-Key.

Parameters

Path

Name	Type	Required	Description
`projectId`	string	Required	The project id. It starts with prj_. Matches `^prj_[0-9a-f]{20}$`.

Query

Name	Type	Required	Description
`limit`	integer	Optional	How many items to return, from 1 to 100. Defaults to 20. From 1 to 100. Default `20`.
`cursor`	string	Optional	The nextCursor value from the previous page. Leave it out to get the first page. From 1 to 512 characters.

Request

List the revisions of an edit.

curl

curl "https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline/revisions" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"

TypeScript

const res = await fetch("https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline/revisions", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Python

import os

import requests

r = requests.get(
    "https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline/revisions",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)

MCP (Full)

{
  "method": "tools/call",
  "params": {
    "name": "list_timeline_revisions",
    "arguments": {
      "projectId": "prj_b9c1f9c7873dcef51a57"
    }
  }
}

Response

A successful call answers HTTP 200.

Fields to check

Name	Type	Description
`hasMore`	boolean	true when there are more items after this page.
`nextCursor`	string or null	Send it as cursor to get the next page. It is null on the last page.

Response example

HTTP 200

{
  "data": [
    {
      "revision": 3,
      "createdAt": "2026-09-01T11:20:00.000Z",
      "source": "api",
      "summary": "Captions on."
    },
    {
      "revision": 2,
      "createdAt": "2026-09-01T11:15:00.000Z",
      "source": "api",
      "summary": "Captions off."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

All response fields

Name	Type	Required	Description
`data`	array of objects	Required	The items of this page.
`data[].revision`	integer	Required	The revision, to restore with restore_timeline (`POST /v1/projects/{projectId}/timeline/restore`).
`data[].createdAt`	string	Required	When the revision was written, in UTC (ISO 8601).
`data[].source`	string	Required	Who wrote it: app is someone in the GPT-Video app, api a call of the public API, assistant the Editor Assistant. One of `app`, `api`, `assistant`.
`data[].summary`	string	Required	What the change did, in short.
`hasMore`	boolean	Required	true when there are more items after this page.
`nextCursor`	string or null	Required	Send it as cursor to get the next page. It is null on the last page.

Errors

Code	Status	When	What to do
`NOT_FOUND`	404	See the error reference.	Change the request, then send it again.
`CONFLICT`	409	The project is not a Vibe Editing project, or its edit was never prepared. Prepare it with prepare_timeline (`POST /v1/projects/{projectId}/timeline/prepare`) first.	Read the resource again, then decide. Do not send the same request again.
`NOT_READY`	409	See the error reference.	Wait for Retry-After, then send the same request again.

Every call can also answer these errors. VALIDATION_FAILED, UNKNOWN_PARAMETER, UNAUTHORIZED, SCOPE_MISSING, RATE_LIMITED, INTERNAL, UNAVAILABLE.

Cost

No credits are used.

restore_timeline (POST /v1/projects/{projectId}/timeline/restore) Restore a revision of an edit
get_timeline (GET /v1/projects/{projectId}/timeline) Get an edit
apply_timeline_operations (POST /v1/projects/{projectId}/timeline/operations) Change an edit

Questions

Why is an older revision missing?

Only the recent revisions of an edit are kept, for a limited time. A revision that is not listed cannot be restored; read the edit with get_timeline (GET /v1/projects/{projectId}/timeline) and change it with apply_timeline_operations (POST /v1/projects/{projectId}/timeline/operations) instead.

Are changes made in the GPT-Video app listed too?

Yes. Every change of the edit is listed, with source app for someone in the GPT-Video app, api for a call of the public API and assistant for the Editor Assistant.

View as Markdown