Welles

HTTP API

REST endpoints for agents and integrations.

Welles exposes a real HTTP API — method, path, scoped bearer auth. The macOS welles CLI is a local wrapper around these routes, not a separate API surface.

Browse endpointsCLI docs
Base URLhttps://api.welles.studio

All paths below are relative to the base URL. Send JSON bodies with Content-Type: application/json unless noted. Responses are JSON.

Example request

curl -X POST "https://api.welles.studio/videos/{id}/export" \
  -H "Authorization: Bearer $WELLES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preset":"web1080"}'

Authentication

Obtain a scoped bearer token via device flow, then pass it on every request.

/device
POST/device/start

Returns a device code for the CLI to poll.

POST/device/poll

Exchange the device code for a scoped bearer token.

POST/token/refresh

Refresh before expiry.

Account

Read the authenticated account and entitlement state before starting paid or quota-bound work.

/me
GET/me

Fetch the current user profile for this bearer token.

GET/me/entitlements

Read plan, quota, feature, and entitlement state.

Projects

Create projects, list visible projects, and retrieve project metadata with the latest edit, shares, and export.

/projects
GET/projects

List projects visible to the authenticated token.

POST/projects

Create a project.

GET/projects/{id}

Fetch project metadata, current edit, shares, and latest export.

GET/projects/{id}/exports

List export jobs for a project.

Videos

Read video records and embedded transcript data.

/videos
GET/videos/{id}

Fetch the full video record with transcript embedded.

Video edits

Read and mutate the edit document. PATCH remains for legacy clients; POST is the canonical shape.

/videos/{id}/edit
GET/videos/{id}/edit

Fetch the current edit document.

PATCH/videos/{id}/edit

Update edit settings using the legacy VideoEditUpdate shape.

POST/videos/{id}/edit

Update edit settings using the canonical { params: { ... } } body.

Transcripts

Fetch transcripts directly or queue transcription with broker fallback.

/videos/{id}/transcript
GET/videos/{id}/transcript

Fetch the transcript as a standalone resource.

POST/videos/{id}/transcribe

Queue transcription, now with broker fallback.

AI automation

Agent-ready video operations for cleanup, zooms, scripts, voiceover, story planning, and slides.

/videos/{id}
POST/videos/{id}/auto-remove-fillers

Remove filler words automatically.

POST/videos/{id}/auto-zoom

Generate automatic zoom moments.

POST/videos/{id}/script

Generate a voiceover or narration script.

POST/videos/{id}/voiceover

Render voiceover audio for the video.

POST/videos/{id}/story/plan

Create a multi-scene story plan.

POST/videos/{id}/slides/generate

Generate slide content for the video.

POST/videos/{id}/slides/render

Render generated slides.

Exports

Queue exports and inspect export job history. Export creation uses broker fallback.

/videos/{id}/exports
POST/videos/{id}/export

Queue an export job, now with broker fallback.

GET/videos/{id}/exports

List export jobs for a video.

Sharing

Create, list, and revoke hosted share links. The singular share route remains available for legacy clients.

/videos/{id}/shares
POST/videos/{id}/shares

Create a hosted share link using the new plural route.

POST/videos/{id}/share

Create a hosted share link using the legacy singular route.

GET/videos/{id}/shares

List hosted share links for a video.

DELETE/videos/{id}/share/{share_id}

Delete a hosted share link.

Token scopes

Request scopes with repeated --scope flags during CLI login, or --all-scopes for trusted local automation.

project:read

GET /projects, GET /projects/{id}, and project export lists.

video:read

GET /videos/{id}, edit reads, transcripts, exports, and shares.

video:edit

PATCH /videos/{id}/edit, POST /videos/{id}/edit, filler removal, and auto-zoom.

video:export

POST /videos/{id}/export and export job reads.

video:share

Create, list, and delete share links.

ai:included

Included-quota script, voiceover, story, and slide operations.

ai:premium

Premium AI operations.

billing:read

Plan checks before premium operations.

CLI wrapper

On macOS, welles record and related verbs call the same backend. Use the CLI for local screen capture; call HTTP directly when your agent runs outside the Mac app.

Read CLI reference →

LLM context

Copy for LLMs

Compact HTTP endpoint list for Claude, Cursor, or another agent.

Welles HTTP API quick reference for LLM agents:

Base URL: https://api.welles.studio

The welles CLI wraps these HTTP routes. Prefer HTTP when orchestrating from a remote agent; use the CLI on macOS for end-to-end recording.

Authentication:
- POST /device/start
- POST /device/poll
- Authorization: Bearer <scoped_token>

Core endpoints:
- GET /me
- GET /me/entitlements
- GET /projects
- POST /projects
- GET /projects/{id}
- GET /projects/{id}/exports
- GET /videos/{id}
- GET /videos/{id}/edit
- PATCH /videos/{id}/edit
- POST /videos/{id}/edit
- GET /videos/{id}/transcript
- POST /videos/{id}/transcribe
- POST /videos/{id}/auto-remove-fillers
- POST /videos/{id}/auto-zoom
- POST /videos/{id}/export
- GET /videos/{id}/exports
- POST /videos/{id}/script
- POST /videos/{id}/voiceover
- POST /videos/{id}/story/plan
- POST /videos/{id}/slides/generate
- POST /videos/{id}/slides/render
- POST /videos/{id}/shares
- POST /videos/{id}/share
- GET /videos/{id}/shares
- DELETE /videos/{id}/share/{share_id}

See /api on welles.studio for the full endpoint list.