api-reference.md

Local API reference

API version 1 (GET /health → api_version). The engine listens on http://127.0.0.1:8765. How to call it, with examples and the gotchas, is in docs/API.md; what the labels promise is in API.

258 routes: 60 stable, 47 experimental, 151 internal.

Label	Promise
stable	Documented as supported in docs/API.md. Changes only by adding; removing or reshaping it bumps the API version. Its request shape is pinned by tests/test_api_contract.py.
experimental	Meant for outside use, but its shape may still change in a release; every change is noted in CHANGELOG.md.
internal	Serves one screen of the desktop app and changes with it. Works, but depending on it is at your own risk.

Readiness

Details: docs/API.md › Readiness.

Route	Label	What it is for
GET /health	stable	Liveness, app version and API version.
GET /health/preflight	stable	Whether a job can actually run here: FFmpeg, Ollama, model, Whisper, GPU, disk.
GET /system/stats	stable	CPU, memory, disk and GPU use.

Submitting work

Details: docs/API.md › Submitting work.

Route	Label	What it is for
POST /jobs	stable	Queue one link with its options.
POST /jobs/batch	stable	Queue several links, each with its own options; bad ones are reported, not fatal.
GET /sports	stable	The sports a job's sport option can name, with their choices.
POST /videos/local	stable	Queue a video file already on this computer.

Watching progress

Details: docs/API.md › Watching progress.

Route	Label	What it is for
POST /cancel	stable	Ask a running video to stop at its next stage boundary.
GET /jobs	stable	Every job, newest last (a bare array).
DELETE /jobs/{job_id}	stable	Remove a job.
GET /jobs/{job_id}	stable	One job.
PATCH /jobs/{job_id}	experimental	Change a queued job's options.
GET /jobs/{job_id}/log	stable	The job's own log file, last lines.
POST /jobs/{job_id}/retry	stable	Queue a failed job again with its original settings.
POST /storage/cleanup	experimental	Remove leftover partial downloads and other temporary files.

The queue

Details: docs/API.md › The queue.

Route	Label	What it is for
GET /queue	stable	The grouped queue the app shows, with capacity and estimate.
POST /queue/pause	stable	Stop claiming new work.
POST /queue/resume	stable	Start claiming work again.

Results

Details: docs/API.md › Results.

Route	Label	What it is for
GET /clips/{clip_id}/captions	stable	A clip's caption lines, clip-relative.
GET /clips/{clip_id}/words	experimental	A clip's words with their times.
GET /media/{clip_id}	stable	A clip's video file.
GET /videos	stable	Every video in the library.
GET /videos/{video_id}/clips	stable	A video's clips with titles, scores and paths.

Models and where the AI runs

Details: docs/API.md › Models and where the AI runs.

Route	Label	What it is for
GET /ai	stable	Where the AI work runs: local or a cloud provider, and the providers offered.
POST /ai/activate	stable	Choose which model does the AI work.
DELETE /ai/providers/{provider_id}/key	stable	Delete a provider's stored key.
PUT /ai/providers/{provider_id}/key	stable	Check and keep a provider's API key.
GET /ai/providers/{provider_id}/models	stable	Models a provider offers for the job, with the user's key.
POST /ai/providers/{provider_id}/test	stable	Check key, reachability and model without spending tokens.
POST /ai/transcription	stable	Choose local Whisper or a provider for transcription.
GET /models	stable	Local models through Ollama, and which one is active.
POST /models/activate	stable	Choose the local model.
POST /models/pull	stable	Download a local model through Ollama.

Languages and export

Details: docs/API.md › Languages and export.

Route	Label	What it is for
PATCH /clips/{clip_id}	experimental	Change a clip's title, schedule and other fields.
POST /clips/{clip_id}/export	stable	Copy a clip to a folder.
POST /export/batch	stable	Copy several clips to a folder.
GET /languages	stable	Languages for captions and translation.
POST /translate	stable	Translate a clip's captions.

Publishing to YouTube

Details: docs/API.md › Publishing to YouTube.

Route	Label	What it is for
GET /clips/{clip_id}/publish	stable	A clip's publishing state.
POST /clips/{clip_id}/publish	stable	Publish one clip.
GET /youtube/status	stable	Whether publishing is available and connected.

Streamer integrations

Details: docs/API.md › Streamer integrations.

Route	Label	What it is for
POST /clips/{clip_id}/thumbnail	experimental	Choose a clip's thumbnail.
POST /clips/{clip_id}/thumbnail/generate	stable	Make thumbnail candidates from the clip's frames.
GET /clips/{clip_id}/thumbnail/generated/{index}	stable	One generated thumbnail candidate.
GET /integrations/presets	stable	Presets a dock can offer.
POST /integrations/streams	stable	Hand over a finished livestream to be clipped when its VOD appears.
DELETE /integrations/streams/{session_id}	stable	Stop waiting for a stream.
GET /integrations/streams/{session_id}	stable	A handed-over stream's progress.
POST /integrations/streams/{session_id}/link	stable	Give the stream's VOD link by hand.
POST /publish/plan	stable	Plan a batch of uploads without doing them.
POST /publish/plan/execute	stable	Carry out a plan.

Watched channels

Details: docs/API.md › Watched channels.

Route	Label	What it is for
GET /automation	stable	Watched-channel settings.
PATCH /automation	stable	Change watched-channel settings.
GET /automation/activity	stable	What the watches did recently.
GET /automation/items	stable	Videos a watch found.
POST /automation/items/{item_id}/publish	stable	Publish a found video's clips.
POST /automation/items/{item_id}/queue	stable	Clip a found video.
POST /automation/items/{item_id}/skip	stable	Skip a found video.
GET /automation/slots	stable	Upcoming publishing slots.
GET /automation/watches	stable	Every watch.
POST /automation/watches	stable	Watch a channel.
DELETE /automation/watches/{watch_id}	stable	Stop watching.
PATCH /automation/watches/{watch_id}	stable	Change a watch.
POST /automation/watches/{watch_id}/check	stable	Check a watch now.

WebSocket events

Details: docs/API.md › WebSocket events.

Route	Label	What it is for
WS /ws	stable	Job, progress, queue, model and publishing events.

Plugins

Details: docs/API.md › Plugins.

Route	Label	What it is for
GET /marketplace	experimental	Listed plugins from the registry indexes, searched and filtered, with what is installed.
GET /marketplace/catalog	experimental	Awesome Clips Kitty's entries built with Clips Kitty (integrations, apps and tools), searched, with their sections, labels and numbers.
GET /marketplace/counting	experimental	Whether installs from the Marketplace are counted, and what counting sends.
PUT /marketplace/counting	experimental	Switch install counting on or off for this PC. Session header.
GET /marketplace/online	experimental	Whether the Marketplace checks Clips Kitty's online list by itself, when it last fetched it and how the last try went.
PUT /marketplace/online	experimental	Switch the Marketplace's automatic checks of Clips Kitty's online list on or off for this PC. Session header.
POST /marketplace/refresh	experimental	Fetch Clips Kitty's online list and the registry index addresses set in settings into the cache; automatic: the online list only, when a day old. Session header.
GET /plugin-models	experimental	Every model the installed plugins list, once: where it is, its licence and size, and which plugins use it.
POST /plugin-models/download	experimental	Download one plugin's model into the shared model folder, checked against its size and SHA-256. Session header.
POST /plugin-models/plan	experimental	What downloading one plugin's model would fetch, from Hugging Face's metadata; downloads nothing. Session header.
GET /plugins	experimental	Installed plugins with their versions, permissions and state, and the built-in modes.
POST /plugins/install	experimental	Install what a plan fetched. Session header.
POST /plugins/plan	experimental	Fetch a plugin from a folder or a Git commit and say what installing it would do, with the install screen as text. Session header.
DELETE /plugins/{publisher}/{name}	experimental	Remove a plugin, its files and its stored keys. Session header.
POST /plugins/{publisher}/{name}/disable	experimental	Turn a plugin off. Session header.
POST /plugins/{publisher}/{name}/enable	experimental	Turn a plugin on. Session header.
POST /plugins/{publisher}/{name}/pin	experimental	Stop update offers for a plugin. Session header.
POST /plugins/{publisher}/{name}/rollback	experimental	Go back to the version installed before. Session header.
PUT /plugins/{publisher}/{name}/secrets	experimental	Store a plugin's secret settings. Session header.
POST /plugins/{publisher}/{name}/unpin	experimental	Offer a plugin's updates again. Session header.

Connected Accounts

Details: docs/API.md › Connected Accounts.

Route	Label	What it is for
GET /connected-accounts	experimental	Providers and sanitized account metadata. Session header.
DELETE /connected-accounts/flows/{flow_id}	experimental	Cancel an unfinished account connection. Session header.
POST /connected-accounts/flows/{flow_id}/poll	experimental	Complete a pending device authorization, respecting polling intervals. Session header.
PUT /connected-accounts/twitch/config	experimental	Set the public Twitch client ID. Never a client secret. Session header.
POST /connected-accounts/twitch/connect	experimental	Start public desktop Twitch device authorization. Session header.
DELETE /connected-accounts/{account_id}	experimental	Stop account operations, revoke authorization and remove local credentials. Session header.
DELETE /connected-accounts/{account_id}/events	experimental	Stop Twitch EventSub and clear retained events. Session header.
GET /connected-accounts/{account_id}/events	experimental	Read bounded sanitized Twitch events. Session header.
POST /connected-accounts/{account_id}/events	experimental	Start host-owned Twitch EventSub subscriptions. Session header.
POST /connected-accounts/{account_id}/test	experimental	Validate a connection and its granted scopes. Session header.
POST /connected-accounts/{account_id}/twitch	experimental	Bounded Twitch context, VOD links, live clips and chat operations. Session header.
POST /connected-accounts/{account_id}/watch	experimental	Add the connected Twitch channel to Watched Channels. Session header.
POST /plugin-accounts/perform	experimental	Run one account action using an expiring, permission-controlled plugin capability.
GET /stream-workflows/{account_id}/digests	experimental	Saved catch-up digests and approval/delivery state. Session header.
POST /stream-workflows/{account_id}/digests	experimental	Prepare an idempotent catch-up digest from verified Twitch sources. Session header.
POST /stream-workflows/{account_id}/digests/{digest_id}/approve	experimental	Approve a catch-up digest; delivery requires a configured host transport. Session header.
GET /stream-workflows/{account_id}/digests/{digest_id}/export	experimental	Export a catch-up digest without claiming delivery. Session header.
DELETE /stream-workflows/{account_id}/monitor	experimental	Stop collecting new nominations without stopping other account consumers. Session header.
POST /stream-workflows/{account_id}/monitor	experimental	Opt in to host-owned viewer nominations for a verified live or upcoming stream. Session header.
POST /stream-workflows/{account_id}/recordings/{stream_id}/retry	experimental	Restart bounded archive discovery for an ended own-channel stream. Session header.
GET /stream-workflows/{account_id}/streams	experimental	Stream identities, aggregate nomination timeline, recording discovery and verified mappings. Session header.
PUT /stream-workflows/{account_id}/vod-mapping	experimental	Verify an explicit stream, VOD and local-source timeline calibration. Session header.

Internal

Everything else. Grouped by the first part of the path; the module is where it is defined.

Area	Routes	Module
/agent	POST /agent/chat GET /agent/status	server.api
/ai	GET /ai/providers/{provider_id}/callback/{state} POST /ai/providers/{provider_id}/connect POST /ai/providers/{provider_id}/stt-check GET /ai/signin/{provider_id} POST /ai/signin/{provider_id}/automation POST /ai/signin/{provider_id}/cancel GET /ai/signin/{provider_id}/models POST /ai/signin/{provider_id}/sign-out POST /ai/signin/{provider_id}/start POST /ai/signin/{provider_id}/test	server.ai_api
/branding	GET /branding POST /branding POST /branding/asset GET /branding/asset/{name} DELETE /branding/{profile_id} PUT /branding/{profile_id}	server.api
/campaigns	GET /campaigns POST /campaigns POST /campaigns/preview GET /campaigns/submissions POST /campaigns/submissions GET /campaigns/submissions/{submission_id} PATCH /campaigns/submissions/{submission_id} POST /campaigns/submissions/{submission_id}/approve POST /campaigns/submissions/{submission_id}/cancel POST /campaigns/submissions/{submission_id}/move POST /campaigns/submissions/{submission_id}/opened POST /campaigns/submissions/{submission_id}/record POST /campaigns/submissions/{submission_id}/retry POST /campaigns/submissions/{submission_id}/submit DELETE /campaigns/{campaign_id} GET /campaigns/{campaign_id} PATCH /campaigns/{campaign_id}	server.campaigns_api
/clips	DELETE /clips/{clip_id} POST /clips/{clip_id}/ai-edit PUT /clips/{clip_id}/captions GET /clips/{clip_id}/creator-gaming-layout PUT /clips/{clip_id}/creator-gaming-layout GET /clips/{clip_id}/frame GET /clips/{clip_id}/glossary POST /clips/{clip_id}/glossary GET /clips/{clip_id}/panels GET /clips/{clip_id}/people GET /clips/{clip_id}/posts POST /clips/{clip_id}/preview POST /clips/{clip_id}/render GET /clips/{clip_id}/snap GET /clips/{clip_id}/source-frame POST /clips/{clip_id}/tighten GET /clips/{clip_id}/translations DELETE /clips/{clip_id}/translations/{language} PUT /clips/{clip_id}/translations/{language}	server.api, server.posts_api, server.youtube_api
/creators	GET /creators POST /creators/merge POST /creators/split/{account_id} DELETE /creators/{creator_id} GET /creators/{creator_id} POST /creators/{creator_id}/accounts POST /creators/{creator_id}/branding DELETE /creators/{creator_id}/knowledge DELETE /creators/{creator_id}/knowledge/{knowledge_id} POST /creators/{creator_id}/learning DELETE /creators/{creator_id}/memory	server.api
/discord	GET /discord/callback POST /discord/clips/{clip_id}/send POST /discord/connect GET /discord/destinations POST /discord/destinations POST /discord/destinations/authorize DELETE /discord/destinations/{destination_id} PATCH /discord/destinations/{destination_id} POST /discord/destinations/{destination_id}/test POST /discord/disconnect GET /discord/guilds POST /discord/parse-link PATCH /discord/settings GET /discord/status	server.discord_api
/feedback	GET /feedback/diagnostics POST /feedback/submit	server.api
/jobs	POST /jobs/{job_id}/move	server.api
/media	GET /media/preview/{clip_id}	server.api
/models	GET /models/pulls DELETE /models/{tag:path}	server.api
/publish	POST /publish/{job_id}/cancel	server.youtube_api
/queue	POST /queue/clear	server.api
/remote-render	GET /remote-render PUT /remote-render POST /remote-render/jobs/{job_id}/retry POST /remote-render/pairing-code PUT /remote-render/this-pc POST /remote-render/this-pc/unpair POST /remote-render/videos/{video_id}/render-locally DELETE /remote-render/workers/{worker_id} POST /remote-render/workers/{worker_id}/hold	remote_render.service
/settings	GET /settings PATCH /settings	server.api
/sources	GET /sources/frame GET /sources/people GET /sources/snap GET /sources/suggest	server.api
/storage	GET /storage GET /storage/videos	server.api
/text-updates	GET /text-updates/channels DELETE /text-updates/credentials PUT /text-updates/discord-bot GET /text-updates/pending PATCH /text-updates/settings GET /text-updates/status POST /text-updates/test	server.text_updates_api
/uploadpost	POST /uploadpost/batch GET /uploadpost/capabilities GET /uploadpost/clips/{clip_id} POST /uploadpost/clips/{clip_id}/publish POST /uploadpost/connect GET /uploadpost/connections DELETE /uploadpost/key PUT /uploadpost/key GET /uploadpost/profiles POST /uploadpost/refresh/{request_id} POST /uploadpost/retry/{request_id} PATCH /uploadpost/settings GET /uploadpost/status	server.uploadpost_api
/videos	GET /videos/local/shape DELETE /videos/{video_id}	server.api
/voices	GET /voices GET /voices/preview	server.api
/woopsocial	POST /woopsocial/batch POST /woopsocial/batch/plan POST /woopsocial/clips/{clip_id}/publish POST /woopsocial/connect GET /woopsocial/connections GET /woopsocial/in-flight DELETE /woopsocial/key PUT /woopsocial/key POST /woopsocial/refresh POST /woopsocial/refresh/{post_id} GET /woopsocial/schedule PATCH /woopsocial/settings GET /woopsocial/status	server.woopsocial_api
/youtube	GET /youtube/categories GET /youtube/connect POST /youtube/connect DELETE /youtube/credentials PUT /youtube/credentials PATCH /youtube/default-account POST /youtube/disconnect GET /youtube/playlists PATCH /youtube/settings GET /youtube/uploads	server.youtube_api