Skip to content

Run Otto, the editing agent

POSThttps://api.vidmoat.com/v1/ai/agent
Bearer tokenScope ai.agent5 creditsTry it in the playground

Describe an edit in message and let Otto emit and apply the commands. One turn per call, charged once: you drive the loop. Works on every plan.

Body#

  • projectIdstringrequired
    The project to edit.
  • messagestringrequired
    The edit, in plain words. Up to 2,000 characters.
  • dryRunbooleandefault false
    Return the planned commands without applying them.

Response#

Returns 200.

Response fields#

  • projectIdstring
    The project.
  • appliedboolean
    Whether the commands were saved.
  • plannerstring
    Which model planned the turn.
  • messagestring
    Otto's reply.
  • commandsarray
    The commands it planned. When it planned none the reply is only { projectId, applied: false, planner, message, commands: [], credits }, and the turn is still charged.
  • 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.
  • unresolvedarray
    Validation failures in the plan that the planner's repair pass could not fix. Feed them into your next turn.
  • lintarray
    Layout warnings: { severity: "warn" | "note", time, message }.
  • suggestedPreviewTimesarray of numbers
    Timestamps worth looking at with the preview endpoint before you render.
  • projectobject
    The project after the turn, summary view.
  • creditsobject
    { charged, remaining }: what this call cost and the balance after it.

Errors#

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

StatusCodeWhen
400invalid_requestmessage or projectId is missing.
404not_foundNo such project, or it is not yours. The two are indistinguishable on purpose.
402insufficient_creditsThe balance cannot cover the call. Nothing ran. remaining is the balance.
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.
422prompt_rejectedThe prompt failed the safety check. Nothing was charged. field names the field.
502provider_errorNo planner answered. The charge is refunded.