Documentación de la API

Cada endpoint, cada parámetro y la misma llamada escrita en 6 lenguajes. URL base https://stealshot.com; toda respuesta es JSON.

Para empezar

No hay nada que instalar ni nada a lo que registrarse. Los endpoints de lectura son abiertos: pegá el cURL de abajo en una terminal y ya usaste la API. Están cacheados en el edge cinco minutos, que es también cada cuánto cambia el corpus, así que sondear más rápido no aporta nada.

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

Autenticación

Solo la necesitan los endpoints marcados con llave requerida — los que responden según quién pregunta. Pasala como bearer token. Las llaves se crean y se revocan en la página de la API, y la llave en sí se muestra exactamente una vez, porque solo guardamos su hash.

Authorization: Bearer $STEALSHOT_KEY

Un pedido sin llave o con una llave revocada recibe un 401 con { code: "unauthenticated" }; una llave válida en un plan que ya no incluye ese endpoint recibe un 403. Ambos son JSON, así que un cliente nunca tiene que parsear una página de error.

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.