Skip to content
VIDMOATDocs

Apply commands

POSThttps://api.vidmoat.com/v1/projects/{id}/commands
Bearer tokenScope projects.writeplan-gated opsTry it in the playground

Apply an ordered list of edit commands. This is the only way to change a timeline, and it is the same reducer the editor calls: anything you can do by hand you can do here.

Path parameters#

  • idstringrequired
    The project id.

Body#

  • commandsarray of objectsrequired
    One to 200 commands, applied in order. Each is an object with a string op and that op's parameters, exactly as listed by GET /v1/schema/commands.
  • dryRunbooleandefault false
    Run the batch without saving and return what would happen.

Response#

Returns 200.

Response fields#

  • projectIdstring
    The project.
  • okboolean
    true only when every command succeeded.
  • dryRunboolean
    Whether anything was saved.
  • resultsarray
    One entry per command: { op, ok, error?, data? }. A failed command is reported here, not as an HTTP error.
  • verificationobject
    What happened: accepted (count), failed ([{ op, error }]), blocked, layout warnings, and outcome (executed, needs-repair or blocked).
  • blockedarray of strings
    Plan-gated features that were dropped.
  • lintarray
    Layout warnings: { severity: "warn" | "note", time, message }.
  • suggestedPreviewTimesarray of numbers
    Timestamps worth looking at with the preview endpoint before you render.
  • timelineobject
    { clipCount, durationSec } after the batch.
  • hintstring
    What to check next.

Errors#

Besides the errors any request can get (authentication, rate limits):

StatusCodeWhen
404not_foundNo such project, or it is not yours. The two are indistinguishable on purpose.
400invalid_requestcommands is missing, empty, longer than 200, or an entry has no string op.
409invalid_requestThe project changed while the batch ran (conflictCode: "stale_rev", with rev) or is locked by an expert handoff (help_handoff_locked). Re-read the project and retry.