---
title: "Run the editing agent"
method: POST
path: "/ai/agent"
tags: ["Generation"]
---

# Run the editing agent

`POST /ai/agent`

## Request

- Base URL: `https://api.vidmoat.com/v1`
- URL: `https://api.vidmoat.com/v1/ai/agent`
- Auth: HTTP bearer

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

Add `dryRun: true` to get the plan back without applying it. The credits are still spent, because the model call is what they pay for, and so is a turn that plans nothing.

## Request body

- object
  - `projectId` string, required: The project to edit.
  - `message` string, required: The edit, in plain words. Up to 2,000 characters.
  - `dryRun` boolean: Return the planned commands without applying them.

## Response `200`

Run the editing agent

- object
  - `projectId` string: The project.
  - `applied` boolean: Whether the commands were saved.
  - `planner` string: Which model planned the turn.
  - `message` string: The agent's reply.
  - `commands` unknown[]: The commands it planned.
    - unknown
  - `results` unknown[]: One entry per command: `{ op, ok, error?, data? }`. A failed command is reported here, not as an HTTP error.
    - unknown
  - `verification` object: What happened: `accepted` (count), `failed` (`[{ op, error }]`), `blocked`, `layout` warnings, and `outcome` (`executed`, `needs-repair` or `blocked`).
  - `lint` unknown[]: Layout warnings: `{ severity: "warn" | "note", time, message }`.
    - unknown
  - `suggestedPreviewTimes` number[]: Timestamps worth looking at with the preview endpoint before you render.
  - `project` object: The project after the turn, summary view.
  - `credits` object: `{ charged, remaining }`: what this call cost and the balance after it.

## Other responses

- `400`: `invalid_request`: `message` or `projectId` is missing.
- `402`: `insufficient_credits`: The balance cannot cover the call. Nothing ran. `remaining` is the balance.
- `404`: `not_found`: No such project, or it is not yours. The two are indistinguishable on purpose.
- `422`: `prompt_rejected`: The prompt failed the safety check. Nothing was charged. `field` names the field.
- `502`: `provider_error`: No planner answered. The charge is refunded.

---

[API](https://skmtc.dev/vidmoat/apis/vidmoat-api.md) · [All operations](https://skmtc.dev/vidmoat/apis/vidmoat-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vidmoat/apis/vidmoat-api/revisions/23e24e25c756?raw)