Get started API reference What it can picture Plans and limits Using the picture When a feed fails Paying

API reference

Every route a customer can call. Everything the dashboard does, the API does.

The basics

• Base address: https://stillframe.us.
• Key: send it in the X-API-Key header on every /api/ call. The image address needs no key.
• Bodies: JSON in, JSON out, except that a pushed picture is the raw file. Send a Content-Length with every body. A JSON body is at most 16 KB and must be an object.
• Rate: 60 calls a minute for each account. Over that, the answer is 429 slow_down with a Retry-After header (seconds).
• API answers are never cached (Cache-Control: no-store). Pictures are; see the first route.
• Errors are {"error": "code", "detail": "words"}. The code is stable; the words may change. Every code is listed in Errors.
• A lapsed subscription: when the account is suspended, every call except GET /api/account answers 402 suspended. Pictures already made are still served at their addresses.
• The dashboard uses a cookie and an X-CSRF header instead of a key. Scripts do not need either.

The feed object

Every call that returns a feed returns this shape.

Settings you can send

Used by POST /api/feeds and PATCH /api/feeds/{id}. A field not in this table is refused with unknown_field.

The address of a page or camera must pass the checks on What it can picture when you make or change the feed, and again every time a picture is taken.

Routes

GET /f/{token}.png and GET /f/{token}.jpg

The feed's newest picture. No key. HEAD works too. Use the extension of the feed's format. After a format change the other extension keeps working too (see PATCH below), so an address someone already embedded does not break.

• 200: the picture. Headers: ETag ("v<version>"), Cache-Control: public, max-age=N, stale-while-revalidate=N, stale-if-error=604800 where N is the feed's refresh time (30 for a push feed), and Access-Control-Allow-Origin: *.
• 304: if you send the current ETag in If-None-Match.
• 404 not_found: no such address. Not cached.
• 404 no_image_yet: the feed exists but has no picture yet. Comes with Retry-After: 5.
• 405 method_not_allowed: any method other than GET and HEAD.

GET /api/account

Your plan, its limits and what you use. Works while the account is suspended.

{"email": "[email protected]", "plan": "standard", "status": "active", "feeds": 3, "feeds_allowed": 20,
 "fastest_refresh_s": 300, "history_kept": 24, "storage_used": 412339, "storage_allowed": 2147483648,
 "choices": {"canvases": [["1920x1080", "1080p, landscape"], ...], "four_k_plans": "Standard and Pro", "four_k_needs": "Standard or Pro", "refresh_s": [300, 600, ...],
             "default_background": "#000000"}}

status is active, past_due, suspended or closed. A closed account has no key.

GET /api/feeds

All your feeds, oldest first: {"feeds": [feed, ...]}.

POST /api/feeds

Make a feed. Body: the settings above. Answers 201 with the feed.

• 400: a setting is wrong. The code names it (see Errors).
• 409 feed_limit: your plan holds no more feeds.

curl -s -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"kind":"page","url":"https://example.com/","canvas":"800x600"}' https://stillframe.us/api/feeds
{"error": "bad_canvas", "detail": "canvas is one of: 1080x1920, 1920x1080, 2160x3840, 3840x2160"}

GET /api/feeds/{id}

One feed. A feed that is not yours is answered exactly like one that does not exist: 404 not_found.

PATCH /api/feeds/{id}

Change any of the settings, sending only what changes. Answers 200 with the feed.

• A change to url, canvas, background, format, wait_s, timezone or allow_blank makes a page or camera feed due at once and clears its failure count, if the value really changed (a field sent back as it was changes nothing). It shares the once-a-minute limit of the render route below: a second change inside the minute is saved and photographed on the feed's usual schedule. On a push feed it draws the last picture you sent again.
• Changing format changes the extension of image_url; the token stays the same. Use the new image_url from then on. Nothing breaks if you do not: until the next picture is taken (a change asks for one straight away), both extensions show the picture that was there before, in its old format and with its true Content-Type; once the new picture exists, both extensions show it, in the new format. A program that decides what a file is from its extension may then show the old address wrongly, which is why the new one is the one to use. A push feed is redrawn from the last picture you sent at once. A format change made while a picture is being taken is redrawn at the next refresh, not straight away.
• The url a camera feed shows has its credentials hidden (see the feed object). If you send that hidden form back (for a camera or a page, with *** where a user, password or query value was), it is refused with bad_url: send the full address, or leave url out.

DELETE /api/feeds/{id}

Remove the feed and its pictures. Answers 200 with {"deleted": id}. Its address stops working.

PUT /api/feeds/{id}/image

Send a picture to a push feed. The body is the file itself; the Content-Type you send is ignored, because the file is read for what it is. At most 10 MB and 50 million pixels, PNG or JPEG. Stillframe draws it again to the feed's canvas and format before serving it, so hidden details in the file are not passed on.

• 200: {"stored": true, "width": W, "height": H, "bytes": N, "image_url": "...", "version": V}
• 400 not_push: the feed is a page or camera feed.
• 413 too_large: over the size limits.
• 415 bad_image: not a PNG or JPEG.
• 422 bad_image: it looked like a PNG or JPEG but could not be drawn.
• 429 slow_down: your plan allows one picture every so many seconds for each push feed (Plans and limits). A push that is let in but then fails (a bad file, say) still uses up its turn.
• 503 compose_failed or launch_failed: Stillframe could not draw the picture. Try again.
• 507 quota: the plan's storage is full. The old picture stays up.

POST /api/feeds/{id}/render

Ask for a page or camera feed to be photographed now. Answers 202 {"queued": id}; the picture arrives when the render finishes. Also clears a failure's slow-down. Once a minute for each feed (429 slow_down otherwise). A push feed answers 400 not_rendered.

POST /api/feeds/{id}/retoken

Give the feed a new address. The old one stops working at once. Answers 200 with the feed. A copy someone already saved elsewhere (an email, a chat) is theirs to lose.

Errors