Publish the draft

curl --request POST \
  --url https://api.streamloop.app/v1/scenes/{id}/publish \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "draftRevision": "<string>",
  "confirm": true,
  "overwritePublished": 2,
  "dryRun": true
}
'

import requests

url = "https://api.streamloop.app/v1/scenes/{id}/publish"

payload = {
    "draftRevision": "<string>",
    "confirm": True,
    "overwritePublished": 2,
    "dryRun": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({draftRevision: '<string>', confirm: true, overwritePublished: 2, dryRun: true})
};

fetch('https://api.streamloop.app/v1/scenes/{id}/publish', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "version": 123,
  "summary": "<string>",
  "publishedAt": "2023-11-07T05:31:56Z",
  "unchanged": true,
  "changes": [
    "<string>"
  ],
  "dryRun": true,
  "notes": [
    "<string>"
  ],
  "stale": true
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "line": 123,
      "path": "<string>",
      "node": "<string>",
      "message": "<string>"
    }
  ],
  "currentRevision": "<string>"
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "line": 123,
      "path": "<string>",
      "node": "<string>",
      "message": "<string>"
    }
  ],
  "currentRevision": "<string>"
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "line": 123,
      "path": "<string>",
      "node": "<string>",
      "message": "<string>"
    }
  ],
  "currentRevision": "<string>"
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "line": 123,
      "path": "<string>",
      "node": "<string>",
      "message": "<string>"
    }
  ],
  "currentRevision": "<string>"
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "line": 123,
      "path": "<string>",
      "node": "<string>",
      "message": "<string>"
    }
  ],
  "currentRevision": "<string>"
}

Publish the draft

Publishes the draft exactly as it was at draftRevision (required: in the body, or as If-Match: "<draftRevision>"; sent both ways, they must name the same draft, else 422 INVALID_INPUT; every draft answer and GET /scenes/ carry the current one), whatever was edited since. It is checked as the channel loads it — the document check, and the type check of script/show.ts, script/state.ts, every frame/<id> and component — and becomes the next version.

When the draft changed after that revision but nobody published since, the answer says so: stale: true and a note (those edits are not in this version; they are still in the draft).
When a version was published after the one that revision’s draft was based on, publishing it would take that version back: 409 STALE_PUBLISH (412 when the draftRevision came as If-Match) names publishedVersion, basedOn and what would be reverted. Read the draft again, or send overwritePublished: <publishedVersion> to replace it anyway. When that version is a revert (publishedVersionIsRevert: true), reading again changes nothing: send overwritePublished to publish the draft over it, or discard the draft to keep the reverted version. Two publishes at once are answered in turn: the second is unchanged at the first one’s version when it publishes the same draft, else that STALE_PUBLISH.
A stream that has the scene on air plays the new version at once: 409 CONFIRM_REQUIRED names the streams; send confirm: true to accept that.
A draftRevision no answer about this scene gave is 422 INVALID_INPUT in the body, 412 PRECONDITION_FAILED as If-Match; one with edits the server doesn’t have yet is 409 DRAFT_NOT_SAVED.

A draft equal to what is published makes no version (unchanged: true). dryRun: true checks it and lists what would change, publishing nothing. Refused with every problem (422 SCENE_INVALID, errors, each with its path and line for a type error). The answer lists the changes as resource paths and notes worth knowing.

POST

scenes

{id}

publish

Publish the draft

curl --request POST \
  --url https://api.streamloop.app/v1/scenes/{id}/publish \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "draftRevision": "<string>",
  "confirm": true,
  "overwritePublished": 2,
  "dryRun": true
}
'

import requests

url = "https://api.streamloop.app/v1/scenes/{id}/publish"

payload = {
    "draftRevision": "<string>",
    "confirm": True,
    "overwritePublished": 2,
    "dryRun": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({draftRevision: '<string>', confirm: true, overwritePublished: 2, dryRun: true})
};

fetch('https://api.streamloop.app/v1/scenes/{id}/publish', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "version": 123,
  "summary": "<string>",
  "publishedAt": "2023-11-07T05:31:56Z",
  "unchanged": true,
  "changes": [
    "<string>"
  ],
  "dryRun": true,
  "notes": [
    "<string>"
  ],
  "stale": true
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "line": 123,
      "path": "<string>",
      "node": "<string>",
      "message": "<string>"
    }
  ],
  "currentRevision": "<string>"
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "line": 123,
      "path": "<string>",
      "node": "<string>",
      "message": "<string>"
    }
  ],
  "currentRevision": "<string>"
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "line": 123,
      "path": "<string>",
      "node": "<string>",
      "message": "<string>"
    }
  ],
  "currentRevision": "<string>"
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "line": 123,
      "path": "<string>",
      "node": "<string>",
      "message": "<string>"
    }
  ],
  "currentRevision": "<string>"
}

{
  "type": "about:blank",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "line": 123,
      "path": "<string>",
      "node": "<string>",
      "message": "<string>"
    }
  ],
  "currentRevision": "<string>"
}

Authorizations

X-API-Key

string

header

required

A Streamloop API key (sl_…). It carries no workspace: send X-Workspace-Id too (400 WORKSPACE_REQUIRED otherwise).

Headers

If-Match

string

The revision (ETag) you read — one, or a comma-separated list of which any current one matches — compared strongly (a weak W/"…" tag never matches): refused with 412 PRECONDITION_FAILED if the resource changed since or no longer exists (the problem carries currentRevision, null when it is gone, and for a layer frameRevision: either is taken). A layer takes its own revision or that of the frame/<id> it is in. *: it must exist. Checked atomically with the write: of two writes sent at once with the same revision, one lands and the other is 412.

Idempotency-Key

string

Retry safely: the key (per caller, workspace, method and path) is taken before the request runs, and its first answer is replayed for 24 hours, with Idempotency-Replayed: true — a repeat sent while the first still runs waits for it. The same key with a different body is 422 IDEMPOTENCY_KEY_REUSED. A 5xx is not kept: the retry runs.

Maximum string length: 200

X-Workspace-Id

string

The workspace to act in. Required with an API key; otherwise the session's own.

Path Parameters

string

required

The scene's id (scn_…)

Pattern: ^scn_

Body

application/json

draftRevision

string

The draft to publish, from the answer you reviewed (or send If-Match)

confirm

boolean

I accept what CONFIRM_REQUIRED named: viewers see this at once

overwritePublished

integer

I accept what STALE_PUBLISH named: replace this published version (its number) and what was published since the draft's base

Required range: x >= 1

dryRun

boolean

Only check, and say what would change

Response

Published (or checked, with dryRun)

version

integer

The published version after this call. On a dry run it is unchanged (0: never published) and the draft would become the next one

summary

string

What happened and what comes next, in a sentence

publishedAt

string<date-time> | null

null on a dry run of a scene never published

unchanged

boolean

The draft was what is published already: no new version

changes

string[]

What changed since the previous version, as resource paths (change frame/main/title props.value, add source/data/hn)

dryRun

boolean

Only checked: nothing was published

notes

string[]

What to know about this publish: edits a pinned draftRevision left in the draft, a revert's draft

stale

boolean

The draftRevision was an older one: the draft has changed since, and those changes are not published

Get started

REST API

Scenes API

MCP server

GraphQL API

Publish the draft

Authorizations

Headers

Path Parameters

Body

Response