Skip to content

api-reference.md

Latest commit

 

History

History
209 lines (166 loc) · 14.7 KB

api-reference.md

File metadata and controls

209 lines (166 loc) · 14.7 KB
Raw

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.

197 routes: 60 stable, 25 experimental, 112 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.

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
/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
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.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
/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
/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