Docs
Log inStart free
API referenceProjects

What happened to a project, and who did it

One described record per change, newest first, from project_events (every writer: the editor, API keys and the connector, agent runs, the Director, the pipeline).

One described record per change, newest first, from project_events (every writer: the editor, API keys and the connector, agent runs, the Director, the pipeline). Before recording started, or while the table is empty or absent, the legacy ledgers (project_edits, changesets, editor_revisions) answer instead: source, recording_since and notes say which. Project-level changes (tempo / conductor, music cues, mix, groove, theme, captions, branding, voice, aspect ratio, ...) are described key by key in changes[]. Every member can list; changes[] is reviewer and above. An API key acts as its account. MCP: get_project_history.

GET
/projects/{id}/history

Authorization

bearerAuth
AuthorizationBearer <token>

Typecut API key. Generate one in app.typecut.ai → Settings → API keys. Send as Authorization: Bearer tc_live_….

In: header

Path Parameters

id*string
Formatuuid

Query Parameters

actor_kind?string
Value in"person" | "agent" | "agent_run" | "director" | "system"
actor?string

A user id, or me (a key has no person: 400). Matches events attributed to that person, including agents acting on their key.

agent_run_id?string
Formatuuid
scene_id?string
Formatuuid
chapter_id?string
Formatuuid
kind?string

A kind PREFIX: project., project.settings, scene.composition.

since?string

ISO timestamp, inclusive.

until?string

ISO timestamp, inclusive.

group_id?string
Formatuuid
limit?integer

Default 50.

Range1 <= value <= 200
cursor?string

next_cursor of the previous page, unchanged.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/history"
{
  "data": {
    "events": [
      {
        "id": "string",
        "at": "string",
        "source": "events",
        "actor": {
          "kind": "person",
          "label": "string",
          "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
          "agent_run_id": "c3317f32-e28b-4af1-a584-86ac8c788dd8",
          "session": "string",
          "is_me": true
        },
        "scope": "project",
        "entity": {
          "type": "scene",
          "id": "string",
          "chapter_id": "string",
          "scene_index": 0,
          "scene_title": "string",
          "chapter_index": 0,
          "chapter_title": "string"
        },
        "kind": "string",
        "domain": "script",
        "sentence": "string",
        "description": "string",
        "changes": [
          {
            "path": "string",
            "area": "string",
            "op": "added",
            "sentence": "string",
            "before": "string",
            "after": "string",
            "derived": true
          }
        ],
        "changes_hidden": true,
        "precise": true,
        "columns": [
          "string"
        ],
        "version": {
          "before": 0,
          "after": 0
        },
        "group": {
          "id": "string",
          "kind": "string",
          "revert_id": "string"
        },
        "group_id": "string",
        "changeset_id": "string",
        "undoes": "string",
        "undone_by": "string",
        "forced": true,
        "count": 0
      }
    ],
    "next_cursor": "string",
    "source": "project_events",
    "recording_since": "string",
    "recording": {
      "state": "recording",
      "since": "string",
      "reason": "no_events"
    },
    "partial": [
      "string"
    ],
    "notes": [
      "string"
    ],
    "viewer": {
      "user_id": "string",
      "role": "owner"
    },
    "filters": {
      "property1": "string",
      "property2": "string"
    }
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}

List the live scene claims in a project GET

Every live claim (people in the editor and agents), longest-held first.

One history event in full GET

The described changes, the structured before -> after rows, the version range, the old values the ledger kept, and pointers to where the rest lives (the editor_revisions row with the previous composit