HTTP API

Every Raspberry Pi frame answers HTTP on port 8787, whether it's standalone, on a self-hosted backend or managed from FrameOS Cloud, and with the backend off or the internet down. This page is the reference: every route, what it takes and what it returns. Controlling the frame covers the web pages around it.

Turn the display off and on

curl -X POST "http://frame:8787/event/turnOff?k=KEY"
curl -X POST "http://frame:8787/event/turnOn?k=KEY"
curl -X POST "http://frame:8787/event/toggleScreen?k=KEY"

KEY is the frame's HTTP access key, from its settings (more on keys). Each call answers {"status":"ok"}. No body is needed, and the frame doesn't look at Content-Type, so sending Content-Type: application/json is fine but optional. These are the events the frame's Turn display off / on menu sends, and a schedule or a scene can send them too.

What happens depends on the display:

A Pi keeps rendering while its display is off, so turnOn brings back the current picture.

From Home Assistant

The Home Assistant add-on doesn't create an entity for the display. A rest_command does the job, and works for any frame, add-on or not:

rest_command:
  frame_display_off:
    url: "http://frame.local:8787/event/turnOff?k=KEY"
    method: post
  frame_display_on:
    url: "http://frame.local:8787/event/turnOn?k=KEY"
    method: post

Then call it from any automation or script:

- alias: "Frame off at bedtime"
  triggers:
    - trigger: time
      at: "23:00:00"
  actions:
    - action: rest_command.frame_display_off

The same pattern covers every other event: switching scenes, changing state fields, asking for a render. Move the URLs into secrets.yaml to keep the key out of your configuration.

Authentication

The frame's access mode decides who needs the key to view and control it. Device commands and the admin API need more, in every mode:

There are three credentials:

• The access key (HTTP access key in the frame's settings; the QR code on the display carries it). Send it as ?k=KEY on any request, or on a POST as Authorization: Bearer KEY, which keeps it out of URLs. Opening /?k=KEY in a browser stores it in a cookie.

• The backend API key (Backend API key in the frame's settings, serverApiKey in frame.json). It's how a backend calls its frames: Authorization: Bearer <key>, on POST only. It opens the control and device routes, but not the admin API.

• An admin session, from the password you set for the frame's admin panel. It's a cookie that lasts 24 hours:

  curl -c frame.jar -H "Content-Type: application/json" \
    -d '{"username": "admin", "password": "…"}' \
    http://frame:8787/api/admin/login
  
  curl -b frame.jar http://frame:8787/api/frames/1/logs

  More than ten login attempts in five minutes get a 429 with Retry-After. A frame that switched its password off for cloud login answers 403.

A request that changes something and carries a browser Origin header must come from the frame's own address. curl, scripts and Home Assistant send no Origin and are unaffected. Behind your own reverse proxy, pass Host through or send X-Forwarded-Host.

Traffic on port 8787 is plain HTTP, key included. If that matters on your network, use HTTPS or a Tailscale tailnet.

Status codes

Viewing and control routes

While the setup hotspot is up, three more are open: GET /wifi (the networks in range), POST /setup (the setup form) and GET /setup/status. /setup/status keeps answering afterwards; the other two answer 400.

Events

POST /event/<name> is how you make a frame do something. The JSON body is the event's payload, and an empty body means {}.

# change state fields on the active scene
curl -X POST "http://frame:8787/event/setSceneState?k=KEY" \
  -H "Content-Type: application/json" \
  -d '{"render": true, "state": {"message": "Dinner at 7!"}}'

# switch to a scene, optionally setting its state on the way
curl -X POST "http://frame:8787/event/setCurrentScene?k=KEY" \
  -H "Content-Type: application/json" \
  -d '{"sceneId": "<scene-uuid>", "state": {"message": "Hello"}}'

# or to the next one in the frame's list
curl -X POST "http://frame:8787/event/setCurrentScene?k=KEY" \
  -H "Content-Type: application/json" \
  -d '{"direction": "next"}'

# render right now
curl -X POST "http://frame:8787/event/render?k=KEY"

# press a button, as if someone pressed it on the frame
curl -X POST "http://frame:8787/event/button?k=KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "A"}'

These take the access key:

Device events

These need an admin session or the backend API key. The access key and public mode can't send them, because that key is on the QR code and shouldn't be able to reboot-loop your frame.

For every event's fields, see the events contract and its notes.

The admin API

These are the routes the admin panel itself calls. All of them need an admin session unless noted. A Pi only knows itself, so its frame id is always 1.

Session

The frame

Assets

Settings, updates and the rest

ESP32 frames

An ESP32 frame answers on port 80, and on HTTPS once its first settings sync has given it a certificate. It has no access key and no access modes, so ?k= does nothing here. Every route except GET /ping needs one of these:

# the frame's API key
curl -X POST http://esp32-frame/event/render -H "Authorization: Bearer API_KEY"

# or the frame's admin login, over HTTP Basic
curl -u admin:PASSWORD http://esp32-frame/status

Either one can send every event the board accepts, device events included.

Four things to watch for:

• A board in deep sleep isn't listening. Send it through the backend or the cloud, which hold the change for its next wake.
• turnOn and turnOff switch the backlight on an LCD. An e-paper board has nothing to switch.
• Some events are Pi only: keyDown, keyUp, textInput, wheel and metrics.
• A board with no admin login answers 403 to anything without its API key, until you set a login from the backend or the board's setup hotspot.

Pico frames

A Pico board answers a small set on port 80, with the frame's API key (Authorization: Bearer) or its device login (HTTP Basic). GET /ping is open.

Each also answers under /api/frames/<id>/. A Pico's scene runs on the backend, so to send it a real event, go through the backend.

Through the backend or the cloud

When a script can't reach the frame, or the frame is asleep, ask whatever manages it. Both take a personal API token, not the frame's key.

A self-hosted backend forwards any event to the frame, with its own key:

curl -X POST "http://<backend>:8989/api/frames/<id>/event/turnOff" \
  -H "Authorization: Bearer fb_api_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Here the Content-Type matters: the backend only reads the body as JSON with that header, and with it the body can't be empty. This route is also how to drive virtual and Pico frames.

FrameOS Cloud queues a command for the frame, which expires after five minutes if the frame doesn't pick it up. <id> is the one in the frame's /frames/<id> page:

curl -X POST "https://cloud.frameos.net/api/frames/<id>/event/turnOff" \
  -H "Authorization: Bearer fc_api_…" \
  -H "Content-Type: application/json" \
  -d '{}'

The cloud takes render, metrics, setCurrentScene, setSceneState, button, uploadScenes, turnOn and turnOff (Pi frames only), and custom events a scene on the frame declares with "origins": ["cloud"]. Anything else is a 404 unsupported_event, and a frame whose firmware is too old answers 409 frame_update_required with the min_frameos_version it needs. The limit is 120 events per 15 minutes.

Both also have an MCP server, if what's calling is an AI agent.