API documentation

Every endpoint, every parameter, and the same call written out in 6 languages. Base URL https://stealshot.com; every response is JSON.

Getting started

There is nothing to install and nothing to sign up for. The read endpoints are open — paste the cURL below into a terminal and you have used the API. They are cached at the edge for five minutes, which is also how often the corpus changes, so polling faster buys nothing.

curl -s "https://stealshot.com/api/search?q=centred+wordmark+on+black"

Authentication

Only the endpoints marked key required need one — the ones whose answer depends on who is asking. Pass it as a bearer token. Keys are made and revoked on the API page, and the key itself is shown exactly once, because we store only its hash.

Authorization: Bearer $STEALSHOT_KEY

A request with a missing or revoked key gets 401 with { code: "unauthenticated" }; a valid key on a plan that no longer includes the endpoint gets 403. Both are JSON, so a client never has to parse an error page.

GET/api/search

Search everything

One term across four kinds of thing at once: videos by title, frames by what a vision model saw in them, brands by name and techniques by slug. A pasted video URL resolves to that one video.

q: The term. Blank returns the strongest rows of each kind rather than nothing.
limit: Rows per group. Capped at 20, default 6.

curl -s "https://stealshot.com/api/search?q=centred+wordmark+on+black&limit=8"

Returns { videos, frames, brands, techniques } — each an array of hits.

Run it in a tab

GET/api/frames

Filter the frame wall

The same query the browse page runs, paged. Every filter is optional and they combine; the response is one deep screenful at a time.

subject: presenter | ui | product | terminal | text-card | b-roll | chart | logo | crowd
surface: camera | screen-recording | motion-graphics | 3d-render | slide | mixed
shot: no-face | corner-inset | wide-presenter | medium-presenter | close-presenter
technique: A named, reusable move. See list_techniques over MCP for the vocabulary.
zone: Where the face sits in the frame.
tone: dark | bright, measured from luminance rather than guessed.
kind: cut | beat | intro — a shot change, a time sample, or an intro frame.
author: Brand or channel name, exact.
platform: youtube | x | linkedin | vimeo | web
q: Free text over the caption, composition, steal and on-screen text.
page: 1-based. 120 frames a page.

curl -s "https://stealshot.com/api/frames?subject=presenter&author=Linear&page=1"

Returns { page, frames, hasMore } — hasMore is true when a full page came back.

Run it in a tab

GET/api/videos/{id}/frames

Every frame of one video

The whole filmstrip in time order, joined to its video so each frame carries the title, author and source URL with it.

curl -s "https://stealshot.com/api/videos/vid_1a2b3c/frames"

Returns { frames } — ordered by t_sec ascending.

Run it in a tab

POST/api/mcp

The MCP server

JSON-RPC over HTTP. The six library tools are open and need no key; presenting a Pro key adds the tools that need to know whose collection — saves, boards, pinning. Most people should install this rather than call it by hand.

curl -s "https://stealshot.com/api/mcp" \
  -X POST \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_frames","arguments":{"query":"how launch videos open"}}}'

Returns A JSON-RPC result whose content is text first, image URL as citation.

GET/api/favouriteskey required

Your saved frames

Everything this account has saved. The first endpoint here that needs a key, because it is the first one whose answer depends on who is asking.

curl -s "https://stealshot.com/api/favourites" \
  -H "Authorization: Bearer $STEALSHOT_KEY"

Returns { frames } — newest save first.

POST/api/favouriteskey required

Save a frame

Idempotent: saving the same frame twice leaves one save.

curl -s "https://stealshot.com/api/favourites" \
  -X POST \
  -H "Authorization: Bearer $STEALSHOT_KEY" \
  -H "content-type: application/json" \
  -d '{"frameId":"frm_9f8e7d"}'

Returns { ok: true }

GET/api/boardskey required

Your boards

Named collections of frames. POST the same path with { name } to make one.

curl -s "https://stealshot.com/api/boards" \
  -H "Authorization: Bearer $STEALSHOT_KEY"

Returns { boards } — each with its item count.