# API reference

> 36 endpoints under https://api.vidmoat.com/v1: projects, commands, renders, media, generation, plugins and Telegram bot users.

## Basics

| | |
| --- | --- |
| Base URL | `https://api.vidmoat.com/v1` |
| Authentication | `Authorization: Bearer <key or token>` ([details](https://developer.vidmoat.com/developer/docs/authentication)) |
| Format | JSON in and out. Media upload is multipart; preview frames are JPEG. |
| Versioning | `Vidmoat-Version` is echoed; additive changes ship into `v1` ([changelog](https://developer.vidmoat.com/developer/docs/changelog)) |

Set `VIDMOAT_KEY` and replace example ids, media URLs and arguments before you send a request. Use a **test** key while you explore: it never spends credits and never queues a real render. The [playground](https://developer.vidmoat.com/developer/playground) in the console runs any endpoint with your own key.

## Responses

Success bodies are specific to each endpoint: a single resource is wrapped in its name (`{ "project": … }`, `{ "render": … }`), and lists are `{ "data": […], "hasMore": true, "nextCursor": "…" }`. Pass `nextCursor` back as `cursor` for the next page (`limit` defaults to 20, at most 100). Telegram bot users page by number instead (`page`, 25 a page). Fields on the plugin and Telegram endpoints are snake_case; everything else is camelCase. Ignore fields you do not recognise.

Failures always look like `{ "error": { "code", "message", "docs_url" } }`. See [errors](https://developer.vidmoat.com/developer/docs/errors).

## Endpoints

## Account

Who the credential belongs to, what it may do, and what it has spent.

| Endpoint | Method and path | Scope |
| --- | --- | --- |
| [Get the current account](https://developer.vidmoat.com/developer/docs/api/account/get-me) | `GET /v1/me` | `account.read` |
| [Get usage](https://developer.vidmoat.com/developer/docs/api/account/get-usage) | `GET /v1/usage` | `account.read` |
| [Get the command schema](https://developer.vidmoat.com/developer/docs/api/account/get-command-schema) | `GET /v1/schema/commands` | none |

## Projects

A project is a timeline document. Every mutation goes through the same command reducer the editor uses, so there is exactly one definition of what an edit means.

| Endpoint | Method and path | Scope |
| --- | --- | --- |
| [List projects](https://developer.vidmoat.com/developer/docs/api/projects/list-projects) | `GET /v1/projects` | `projects.read` |
| [Create a project](https://developer.vidmoat.com/developer/docs/api/projects/create-project) | `POST /v1/projects` | `projects.write` |
| [Get a project](https://developer.vidmoat.com/developer/docs/api/projects/get-project) | `GET /v1/projects/{id}` | `projects.read` |
| [Update a project](https://developer.vidmoat.com/developer/docs/api/projects/update-project) | `PATCH /v1/projects/{id}` | `projects.write` |
| [Delete a project](https://developer.vidmoat.com/developer/docs/api/projects/delete-project) | `DELETE /v1/projects/{id}` | `projects.write` |
| [Apply commands](https://developer.vidmoat.com/developer/docs/api/projects/apply-commands) | `POST /v1/projects/{id}/commands` | `projects.write` |
| [Validate commands](https://developer.vidmoat.com/developer/docs/api/projects/validate-commands) | `POST /v1/projects/{id}/validate` | `projects.read` |

## Workspaces

A workspace is a folder for projects: a client, a series, a campaign. It is NOT a team: a team decides who can see a project, a workspace decides what body of work it belongs to, and a project carries both. Workspaces use the projects scopes rather than having their own, so keys you have already minted can use them.

| Endpoint | Method and path | Scope |
| --- | --- | --- |
| [List workspaces](https://developer.vidmoat.com/developer/docs/api/workspaces/list-workspaces) | `GET /v1/workspaces` | `projects.read` |
| [Create a workspace](https://developer.vidmoat.com/developer/docs/api/workspaces/create-workspace) | `POST /v1/workspaces` | `projects.write` |
| [Update a workspace](https://developer.vidmoat.com/developer/docs/api/workspaces/update-workspace) | `PATCH /v1/workspaces/{id}` | `projects.write` |
| [Delete a workspace](https://developer.vidmoat.com/developer/docs/api/workspaces/delete-workspace) | `DELETE /v1/workspaces/{id}` | `projects.write` |
| [File a project](https://developer.vidmoat.com/developer/docs/api/workspaces/set-project-workspace) | `PUT /v1/projects/{id}/workspace` | `projects.write` |

## Rendering

Renders are queued, not synchronous. A 5-second clip takes seconds; a three-minute one takes minutes. Preview frames are synchronous and spend no export allowance.

| Endpoint | Method and path | Scope |
| --- | --- | --- |
| [Queue a render](https://developer.vidmoat.com/developer/docs/api/renders/create-render) | `POST /v1/renders` | `render.write` |
| [List renders](https://developer.vidmoat.com/developer/docs/api/renders/list-renders) | `GET /v1/renders` | `render.read` |
| [Get a render](https://developer.vidmoat.com/developer/docs/api/renders/get-render) | `GET /v1/renders/{id}` | `render.read` |
| [Preview a project](https://developer.vidmoat.com/developer/docs/api/renders/get-preview) | `GET /v1/projects/{id}/preview` | `render.read` |

## Media

Bring footage in. Everything you upload is attributed to the app owner's account, and the usual moderation applies.

| Endpoint | Method and path | Scope |
| --- | --- | --- |
| [List media](https://developer.vidmoat.com/developer/docs/api/media/list-media) | `GET /v1/media` | `media.read` |
| [Upload a file](https://developer.vidmoat.com/developer/docs/api/media/upload-media) | `POST /v1/media/uploads` | `media.write` |
| [Import from a URL](https://developer.vidmoat.com/developer/docs/api/media/import-media) | `POST /v1/media/import` | `media.write` |
| [Search stock media](https://developer.vidmoat.com/developer/docs/api/media/search-stock) | `GET /v1/stock/search` | `stock.read` |

## Generation

These spend credits, and they are the reason scopes exist. Images, speech, stickers and video run the prompt-safety check on their text first; a refusal is a 422 with a reason, never a silent empty result, and is not charged. Images, speech, stickers, transcription and the agent answer synchronously; video is a job you poll.

| Endpoint | Method and path | Scope |
| --- | --- | --- |
| [Transcribe media](https://developer.vidmoat.com/developer/docs/api/generation/create-transcription) | `POST /v1/ai/transcriptions` | `ai.transcribe` |
| [Generate speech](https://developer.vidmoat.com/developer/docs/api/generation/create-speech) | `POST /v1/ai/speech` | `ai.speech` |
| [Generate an image](https://developer.vidmoat.com/developer/docs/api/generation/create-image) | `POST /v1/ai/images` | `ai.image` |
| [Generate a sticker](https://developer.vidmoat.com/developer/docs/api/generation/create-sticker) | `POST /v1/ai/stickers` | `ai.image` |
| [Generate a video](https://developer.vidmoat.com/developer/docs/api/generation/create-video) | `POST /v1/ai/videos` | `ai.video` |
| [Bring a still to life](https://developer.vidmoat.com/developer/docs/api/generation/create-live-image) | `POST /v1/ai/live-images` | `ai.video` |
| [Get a generation job](https://developer.vidmoat.com/developer/docs/api/generation/get-generation-job) | `GET /v1/ai/jobs/{id}` | `ai.video` |
| [Run the editing agent](https://developer.vidmoat.com/developer/docs/api/generation/run-agent) | `POST /v1/ai/agent` | `ai.agent` |

## Plugins

Discover installed or owned plugins, then call a tool by its published schema. Fields on these endpoints are snake_case.

| Endpoint | Method and path | Scope |
| --- | --- | --- |
| [List plugins](https://developer.vidmoat.com/developer/docs/api/plugins/list-plugins) | `GET /v1/plugins` | `account.read` |
| [Call a plugin tool](https://developer.vidmoat.com/developer/docs/api/plugins/invoke-plugin-tool) | `POST /v1/plugins/{slug}/{tool}` | `plugins.invoke` |

## Telegram bot users

The people using the Telegram bot connected to this key's app: list them, allow or revoke them, block them, set their daily limit. The building block for selling access. Fields on these endpoints are snake_case. The key must be minted for the app whose bot you manage, and these scopes are never inherited by older keys.

| Endpoint | Method and path | Scope |
| --- | --- | --- |
| [List bot users](https://developer.vidmoat.com/developer/docs/api/telegram-users/list-telegram-users) | `GET /v1/telegram/users` | `telegram.users.read` |
| [Get a bot user](https://developer.vidmoat.com/developer/docs/api/telegram-users/get-telegram-user) | `GET /v1/telegram/users/{user}` | `telegram.users.read` |
| [Update a bot user](https://developer.vidmoat.com/developer/docs/api/telegram-users/update-telegram-user) | `PATCH /v1/telegram/users/{user}` | `telegram.users.write` |

---

Source: https://developer.vidmoat.com/developer/docs/api
Previous: [Build your own video platform](https://developer.vidmoat.com/developer/docs/build.md)
Next: [Get the current account](https://developer.vidmoat.com/developer/docs/api/account/get-me.md)
All documentation: https://developer.vidmoat.com/llms-full.txt