countdown

Something happens at a known moment and the reader wants to know how long until it does: a launch, a race, a deadline, a flight.

A countdown to a named moment — the event, the time left, and the local wall clock where it happens.

There’s no reference render of this type yet. The examples below show what to send.

Fields in data

The envelope around data (publisher, label, expiresAt…) is the same on every type: see the envelope.

How it renders

• event is the card's headline, set at display size. It's the subject line — the remaining time is drawn from target, not from anything you write.
• The remaining time is computed on the reader's device from target (returned as UTC). The client corrects for device clock skew against the server's Date response header, so the count is honest even when the phone's clock isn't.
• When timezone is present, the card can also print the event's local wall-clock time in that zone — the one thing an offset alone can't do once daylight saving moves.
• sub sits on one line under event; roughly 40 characters before it wraps.
• What the card shows after target passes is decided by the client, not the server.

Craft

• event is the subject, 1–4 words: "Melbourne Cup", "v2.0 launch", "Tax return due". It sets at display size — past about 28 characters it wraps.
• target is an ISO-8601 instant WITH its offset: "2026-11-03T15:00:00+11:00" or "2026-11-03T04:00:00Z". A datetime with no offset is rejected — "18:00" means nothing until you say where.
• Send timezone whenever the event happens somewhere in particular — the IANA id ("Australia/Melbourne"), not an abbreviation ("AEST"). It's how the card can say "3:00 pm Melbourne time" and stay right across a daylight-saving change.
• Write target in the event's own local offset if you can. The server stores the UTC instant and keeps your offset alongside, so either works — but the local form is the one a human can check.
• sub is one line of context under the event name, about 40 characters: "Flemington · Race 7", "Doors 7pm, headliner 9:30".
• Set expiresAt to target plus a short grace window — an hour for a race, a day for a deadline. A countdown that has already fired is clutter. The server doesn't enforce this; the feed just looks better when you do.
• Once the target passes, what the card shows is the client's business — don't republish to flip it to "happening now".

Avoid

• Don't send a naive datetime ("2026-10-04T18:00:00") and hope it's read as UTC — it's rejected.
• Don't send an abbreviation or fixed-offset zone as timezone ("AEST", "EST", "Etc/GMT-10") — they're ambiguous and don't follow DST. Use "Australia/Melbourne".
• Don't pre-compute the remaining time ("3 days") into event or sub — the card counts down live, so a baked-in figure is wrong a minute later.
• Don't publish a countdown to something already past, or years away. The first is a dead card; the second is a number too big to feel.
• Don't format the target date into sub for the reader — the client formats it in their locale, and in timezone when you send one.

Examples

Complete payloads for POST /api/v1/feed/items or the MCP publish_pane tool.

{
  "type": "countdown",
  "publisher": "Racing.com",
  "publisherInit": "R",
  "publisherColor": "#0B3D2E",
  "label": "Race day",
  "data": {
    "event": "Melbourne Cup",
    "target": "2026-11-03T15:00:00+11:00",
    "timezone": "Australia/Melbourne",
    "sub": "Flemington · Race 7"
  }
}

{
  "type": "countdown",
  "publisher": "Linear",
  "publisherInit": "L",
  "publisherColor": "#5E6AD2",
  "label": "Launch",
  "data": {
    "event": "v2.0 goes live",
    "target": "2026-10-14T16:00:00Z",
    "sub": "Freeze at noon, go/no-go at 3pm"
  }
}

{
  "type": "countdown",
  "publisher": "Accountant",
  "publisherInit": "A",
  "publisherColor": "#1A4FCC",
  "label": "Deadline",
  "data": {
    "event": "Tax return due",
    "target": "2026-10-31T23:59:00+11:00",
    "timezone": "Australia/Sydney"
  }
}