# Update a project

`PATCH https://api.vidmoat.com/v1/projects/{id}`

- Scope: `projects.write`
- Cost: Free

Rename, or change output settings: aspect ratio, frame rate, background, width and height. Timeline edits go through commands.

> **Note.** Send at least one field. A value the editor rejects (an unknown aspect ratio, for example) comes back as a failed entry in `results` with a 200, not as an HTTP error.

### Path parameters

- `id` (string, required): The project id.

### Body

- `name` (string, optional): Up to 80 characters. Must not be empty.
- `aspectRatio` (enum, optional): Also sets width and height (for example `9:16` is 1080x1920). One of `16:9`, `9:16`, `1:1`, `4:5`, `4:3`, `21:9`.
- `fps` (number, optional): 1 to 120.
- `background` (string, optional): CSS colour.
- `width` (integer, optional): Pixels. Applied after `aspectRatio`.
- `height` (integer, optional): Pixels. Applied after `aspectRatio`.

## Response

Returns `200`.

### Response fields

- `project` (object): Summary view, after the change.
- `results` (array): One entry per command: `{ op, ok, error?, data? }`. A failed command is reported here, not as an HTTP error.
- `verification` (object): What happened: `accepted` (count), `failed` (`[{ op, error }]`), `blocked`, `layout` warnings, and `outcome` (`executed`, `needs-repair` or `blocked`).

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 404 | [`not_found`](https://developer.vidmoat.com/developer/docs/errors#not_found) | No such project, or it is not yours. The two are indistinguishable on purpose. |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | No supported field was sent, or `name` is empty. |
| 409 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | The 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. |

## Request examples

```bash curl
curl -X PATCH https://api.vidmoat.com/v1/projects/$ID \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Renamed"}'
```

```js Node
const ID = 'YOUR_PROJECT_ID';

const res = await fetch(`https://api.vidmoat.com/v1/projects/${ID}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Renamed',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

ID = "YOUR_PROJECT_ID"

res = requests.patch(
    f"https://api.vidmoat.com/v1/projects/{ID}",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "name": "Renamed",
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "project": {
    "id": "cm1abc",
    "name": "Launch teaser",
    "createdAt": "2026-09-30T10:00:00.000Z",
    "updatedAt": "2026-10-02T09:00:00.000Z",
    "durationSec": 12.5,
    "clipCount": 4,
    "settings": { "aspectRatio": "9:16", "width": 1080, "height": 1920, "fps": 30, "background": "#000000" },
    "workspace": null
  },
  "results": [{ "op": "setProjectSettings", "ok": true }]
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/projects/update-project
Previous: [Get a project](https://developer.vidmoat.com/developer/docs/api/projects/get-project.md)
Next: [Delete a project](https://developer.vidmoat.com/developer/docs/api/projects/delete-project.md)
All documentation: https://developer.vidmoat.com/llms-full.txt