API referenceScenes
What is true at this moment of the project
The read to make BEFORE authoring anything that has to land ON something — a brand-mark formula, a cue, a reactive overlay.
It answers, in one call, the questions that decide whether an authored thing will actually fire:
- narration — the words this scene speaks and the second each is HEARD. Already on the timeline clock, so pauses and silence trims are applied;
retimedsays whether this block has any. A cue addressed at a word from this list will resolve. - rulers — the grid a formula resolves against, and the cues already resolved to
hit:<name>.source: "archetype"means the 100 BPM fallback, not the track. - cues — each authored cue with
resolvesAt.nullmeans it will NEVER fire, which is otherwise invisible until you watch the export and see nothing happen. - signals — whether an audio signal exists to bind to, and its channels.
- mark — what the bug is set to now, and which slugs it can take.
Assembled from the renderer's own functions, so what you read here and what the MP4 does are one computation rather than two that ought to agree. It does not restate structure or composition — GET /scenes/{sceneId} returns the source.
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
sceneId*string
Format
uuidResponse Body
application/json
application/json
application/json
curl -X GET "https://example.com/scenes/497f6eca-6276-4993-bfeb-53cbbbba6f08/context"{
"data": {
"scene": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"title": "string",
"chapter_id": "88d12d31-77f2-44df-910e-b37f83274f80",
"block_id": "string",
"duration": 0
},
"narration": {
"text": "string",
"words": [
{
"word": "string",
"startSec": 0,
"endSec": 0
}
],
"clock": "timeline",
"retimed": true,
"basis": "timestamps"
},
"rulers": {
"source": "score",
"bpm": 0,
"bars": [
0
],
"beats": [
0
],
"hits": [
{
"name": "string",
"at": 0
}
],
"cam": [
{
"name": "string",
"t": 0
}
]
},
"cues": [
{
"name": "string",
"at": 0,
"resolvesAt": 0
}
],
"signals": {
"available": true,
"source": "music",
"channels": [
"string"
],
"normalisation": "per-source-p99"
},
"mark": {
"enabled": true,
"position": "string",
"scale": 0,
"opacity": 0,
"formula": "string",
"available": [
"string"
]
}
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}