Push a single picture to a panel

[haarts]

In the web UI you can upload a single image and push that to a panel. I would like to do that via a script.

I've read the OpenAPI spec. I believe I need /api/v1/push. But I do not know what the payload of that request then needs to be. Especially the page_id key. The spec reads: "Id of the saved page to render + publish". How do I get that page_id? What is a page? Is that the same as a dashboard?

Thank you in advance for any help you might be willing to render.

I've installed Tesserae as an app in Home Assistant.

[dmellok]

Your reading of the spec was right, and the spec was the problem. Answers first,
then something new to try.

What a page is. Page and dashboard are the same thing; "page" is the older
internal name that leaked into the API. The id is the slug in its URL: open a
dashboard and you'll be at /pages/<page_id>, and that string is what
/api/v1/push wants.

Why it couldn't do what you asked. /api/v1/push re-renders a saved
dashboard. There is no image parameter and no way to add one, so for a
one-off picture it was the wrong endpoint and you weren't missing a trick.
There was a way to do it, through the Companion API used by the iOS app, but
that isn't in the public spec, so you had no way to find it. The spec should
have covered this case.

New endpoint, on edge now. POST /api/v1/push/image does exactly what you
described, with the same webhook token you already need for /push:

curl -sS -X POST http://<your-host>:8765/api/v1/push/image \
  -H "Authorization: Bearer $TESSERAE_TOKEN" \
  -F image=@photo.jpg \
  -F device_ids=hallway \
  -F fit=fill

{"status": "sent", "sent": ["hallway"], "quiet": [], "failed": []}

Notes:

• The token comes from Settings → System → Webhook, the same one /push
  uses. (The spec and docs said Server → App until today. That was wrong, and
  is fixed in the same build.)
• device_ids is required here. A dashboard knows which panels it belongs to;
  a loose image doesn't, and quietly fanning it out to every panel in the house
  seemed like the wrong default. Comma-separated or a repeated -F both work.
• fit is optional: fit, fill, blur, stretch, center.
• Quiet hours still apply. A panel inside its window comes back under quiet
  with a 202 rather than being reported as sent, so a script can tell a skip
  from a failure. Add -F override_quiet_hours=true when the picture is worth
  waking a panel for anyway, a doorbell snapshot rather than ambient art.
• The image is fitted and dithered to each panel exactly as the Send page does,
  so you get the same result you get by hand.

One thing to watch, since you're on the Home Assistant App. Call the
instance directly on its port, not through the ingress URL in the sidebar.
Ingress is authenticated for your browser session, so a script hitting it will
just get bounced.

It's on the edge build, not a release yet. If you're able to try it and tell me
whether it does what you need, I'll take that as the signal to cut it into a
release; if the shape is wrong for your script, better to hear that before it
becomes a stable contract. And if you'd rather not run edge, say so and I'll
write up the way to do it on the current release instead.

[haarts]

My man!

I parallel installed edge, reflashed my panel with the new connection params (port 8766, instead of 8765), connected it and did the curl request as show. That worked! Frickin' neat.
At first I didn't know it worked since the image didn't immediately show. But then I remembered that the panel phones home regularly. So a small delay (couple of seconds/minutes) is expected.

One thing I noticed is that the image I send is rotated 90 degrees. The image I send is taller than it is wide (portrait). I haven't figured out how to influence that rotation.

[dmellok]

Two different things were behind that, and one was a bug.

Your photo's own orientation was being dropped. A phone shooting in
portrait doesn't rotate pixels; it stores a landscape buffer plus an EXIF
orientation tag and lets the viewer turn it. The .bin renderers apply that
tag while fitting to the panel, but the pi_png renderer fits on the client
and never called it, so the tag was lost on re-encode and the panel painted
the photo a quarter-turn off. Orientation is now applied once when the image
is taken in, before any renderer sees it. Edge, v0.309.0.

There was also no way to ask for a turn. /api/v1/push/image takes
rotate now:

curl -sS -X POST http://<your-host>:8766/api/v1/push/image \
  -H "Authorization: Bearer $TESSERAE_TOKEN" \
  -F image=@photo.jpg -F device_ids=hallway -F rotate=auto

auto turns the image a quarter only when its aspect is the opposite of the
panel's, so a portrait photo fills a landscape panel instead of arriving as a
letterboxed strip. rotate=90|180|270 turns it clockwise by that much
regardless. Left out, the image keeps the orientation it was shot in, which is
what you want for anything carrying text. The same picker is on the Send page
now, so the UI and a script describe a turn the same way.

If the panel itself is mounted the other way around, neither of those is
the right knob: set Rotation on the display in Settings → Devices, and your
dashboards land upright too rather than just this one image. A quick way to
tell which you're hitting: if everything you push is turned, it's the mount;
if only camera photos are, it was the EXIF bug.

On the delay, that's the panel's wake interval, nothing is queued behind it.
Sleep interval is per display in Settings → Devices if you want it tighter, at
the usual battery cost.

Which client is on that panel, and did the photo come off a phone? That tells
me whether the fix covers your case or whether it's the mount.

[haarts]

I intent to push a web comic there, Poorly Drawn Lines. So an image like this one: https://poorlydrawnlines.com/wp-content/uploads/2026/08/contemplating.png.

My panel is in landscape mode, the default. Device orientation is set at 0 degrees. That makes sense. I've noticed the interval too, set at the default of 1m.

Not sure what you mean by 'client' on the panel. You mean the firmware version my panel runs? It's the latest: v1.13.0.

[dmellok]

Different cause than either of the ones I guessed. The mono and greyscale
ESP32 renderers were deciding the quarter turn from the image's aspect
instead of the panel's, so anything taller than it is wide got turned on a
landscape panel. Nothing to do with EXIF or your mount. Fixed on edge in
v0.309.1: pull edge again and the comic should land upright with white bands
either side, no rotate needed. -F fit=fill if you'd rather it filled the
panel.

Separately, I built a Poorly Drawn Lines widget while I was in here and I'll
put it in the catalog, so it's a couple of clicks instead of a curl script.

Which might be jumping the gun. If half the fun was wiring up the push
yourself, say so and I'll leave the next one to you. And if there's another
widget you want, I'm happy to build it.

[haarts]

Hahaha! Thanks for the widget. I was gunning for functionality, not the CLI exercise.

I'll be pulling later today.