API

Endpoints

GET /api/v1

Name, docs URL, endpoint list. No key.

GET /api/v1/wallpapers

format=phone|desktop|ultrawide|superwide · sort=newest|oldest|hue|likes|downloads

Returns { "count", "wallpapers" }. Skip format for all. ultrawide includes superwide. superwide is only ≥3:1. sort=hue walks the wheel from red (hues near 360 sit next to 0); missing hue last.

GET /api/v1/wallpapers/{id}

One wallpaper. Id is the filename without extension, e.g. aug142026-2. Unknown id: 404.

GET /api/v1/latest

format=phone|desktop|ultrawide|superwide · default desktop

One wallpaper, plus requested (the format you asked for) and fallback. fallback is true only if nothing existed in that format, so this is the newest of any shape. Superwide when you asked for ultrawide is not a fallback.

GET /api/v1/works

color · tag · format=phone|desktop|ultrawide|superwide

Returns { "count", "works" }. Newest first. A work is one titled piece that has a public page. color and tag are slugs (purple, abstract). A basic color matches every shade under it; a shade like violet matches only that shade. format keeps works that have an image in that shape and drops the other sizes, including video. ultrawide includes superwide.

GET /api/v1/works/{id}

One work. Id is the slug, e.g. aurora-reprise, or a hue number, e.g. HUE-0001. Unknown id: 404.

GET /api/v1/collections

Returns { "count", "collections" }. Public collections only. Drafts are omitted, and a draft id is 404.

GET /api/v1/collections/{id}

One public collection. works is the curated order: { id, title, url, thumb }.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://perfecthue.com/api/v1/works/aurora-reprise

Each wallpaper

Each work

Channel file

A whole day of your channel as JSON. Import it from your channel’s ⋯ menu, or send it to PUT /api/v1/tv/me.

{
  "timezone": "America/Denver",
  "repeat": true,
  "schedule": [
    { "at": "18:00", "video": "https://youtu.be/XXXXXXXXXXX" },
    { "video": "https://youtu.be/YYYYYYYYYYY", "length": "12:30" },
    { "at": "20:00", "playlist": "https://www.youtube.com/playlist?list=PL…", "until": "23:00", "order": "shuffle" }
  ]
}

How it plays

• Items play back to back from midnight, or from the first item’s at. Later times count on from there, so "02:00" after "18:00" is the next morning.
• A gap before an at is dead air. A video that runs past the next at is cut short.
• A playlist fills until its until, the next at or the end of the day, skipping videos too long for what’s left.
• Videos up to 60 minutes, 400 a day (2,800 for a week), 3 playlists per file.
• Videos that can’t play or don’t fit are skipped and listed in warnings.
• Importing replaces your videos. Live shows and premieres stay.
• With day, each day plays like a file of its own. A file without days on a channel that loops a week goes on every day.
• Channels run on UTC, so after a clock change local times move by an hour.

Endpoints

GET /api/v1/tv/channels

Returns { "count", "channels" }, busiest first. Only channels with videos on them.

GET /api/v1/tv/channels/{slug}

timezone · default UTC

Returns { "channel", "schedule" }. The slug is the end of the channel’s address, e.g. cooking-channel. schedule is a channel file of its videos.

GET /api/v1/tv/me

timezone · default UTC

channel · slug or id of one of your channels · default your first

Your channel and its schedule. Both null when you don’t have one.

PUT /api/v1/tv/me

channel · as above

Body: a channel file. Replaces your videos and makes your channel if you don’t have one. Returns { "channel", "added", "removed", "filled", "warnings", "schedule" }. filled is seconds.

POST /api/v1/tv/check

Body: a channel file. What it would put on, without saving. Returns { "videos", "filled", "warnings", "schedule" }.

Checks and replaces: 20 an hour, shared with Import. Send the key in the header for these, not ?key=.

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data @channel.json \
  https://perfecthue.com/api/v1/tv/me

Each channel