Card data API

Discover built-in cards from this environment's published catalogue, merged with the vendored floor. Refreshes and schema verification happen in the background; this route never calls the edge bucket. Each entry lists its current copy, its tier and the layouts that tier allows, and every served major.

The current major's self-contained JSON Schemas for placement params and card-data documents, feed schema, tier, allowed layouts and an example placement. Params marked dynamic come from the data document when a placement binds a data key.

A string param may carry {screen.name}, {screen.timezone} and {screen.field.NAME}, and a location param may be the string {screen.location}; the backend expands them for each screen. Replace example content values before publishing. Unknown ids answer card_not_found (404).

A global card UID, or a deprecated catalogue type segment. The latter adds Deprecation and Warning headers pointing to /api/card-types.

If-Match optionally compares the card metadata revision (not its data revision); omission updates the current revision. Idempotency-Key binds the method, UID, params and If-Match for 24 hours. A retry replays the recorded result, including 204 after deletion; changed input returns idempotency_mismatch. Stale If-Match returns revision_conflict (412).

Keys are scoped to the card UID.

If-Match optionally compares the card metadata revision (not its data revision); omission updates the current revision. Idempotency-Key binds the method, UID, params and If-Match for 24 hours. A retry replays the recorded result, including 204 after deletion; changed input returns idempotency_mismatch. Stale If-Match returns revision_conflict (412).

Keys are scoped to the card UID.

Lists the card's incoming webhooks, oldest first (at most 20). Secrets are never returned here.

Creates a webhook that writes this card's data document: an outside system posts a JSON or form body to its url (POST /api/cards/{id}/kv-webhooks/{webhook_id}/write).

Without a mapping the posted object is the document; a mapping template builds it from the body and is checked when saved. signing true also requires a ScreenRig-Signature header. verify makes a vendor's own signature (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana or any HMAC sender) authenticate a post in place of the secret, which keeps working beside it; it cannot be combined with signing, and its secret is sealed and never returned, only a hint of it. handshake names a vendor handshake the url answers (Microsoft Graph, monday.com, Trello or Azure Event Grid; verify slack and asana answer theirs).

The answer is the only place the secret and the signing secret appear (with rotate-secret and the update that turns signing on): store them in the sending system at once. A card has at most 20 webhooks (kv_webhook_limit_reached). Appends kv_webhook.created.

An exact retry with the same Idempotency-Key returns the same answer, secrets included, for twenty-four hours.

Changes description, mapping (null removes it), enabled, signing, verify (null removes it; without a secret it keeps the stored one when the vendor is the same) and handshake (null removes it). Turning signing on answers the new signing_secret once; false turns it off. A disabled webhook answers every post like a wrong secret. Appends kv_webhook.updated.

Deletes the webhook. Its url stops working at once; the card keeps its document. Appends kv_webhook.deleted.

Replaces the webhook's secret and returns the new one once; with signing true it replaces the signing secret instead. The old one stops working at once. Appends kv_webhook.secret_rotated.

The webhook's delivery log, newest first, at most 100, kept for seven days.

Each post that named this webhook is a row with its time, outcome (written, unchanged, refused, invalid or handshake), reason (credentials, signature, signature_missing, signature_invalid, timestamp_missing, timestamp_stale, secret_pending, handshake_invalid, disabled, body, mapping, card_data_invalid, rate_limited, payment_required, internal), a short detail such as the card data path that failed, the answer's status, the body size and the number of file parts a multipart post carried (ignored).

No body, header or credential is stored. This is where a project sees why a post got the 404 every refusal shares.

The url an outside system posts a card's data document to. It authenticates with the webhook's own secret in the Authorization header: Bearer <secret>, or HTTP Basic with the webhook id as the username.

When the webhook was created with verify, a valid signature in that vendor's own header (see WebhookVerifyWrite) authenticates the post in place of the secret, which keeps working beside it.

When the webhook signs, ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret> is also required, and t must be within five minutes of the server's clock.

An unknown card or webhook, a wrong or missing secret or signature, a stale timestamp, a disabled webhook and every GET answer the same 404 not_found; the project sees the reason in the delivery log.

A webhook set up for a vendor handshake answers it first, before any credential is asked for, to a request that is that handshake: Slack's url_verification challenge (signed, answered with the challenge), Microsoft Graph's validationToken (echoed as text/plain), Asana's X-Hook-Secret (echoed, and kept sealed as the signing secret of its events), monday.com's challenge, Azure Event Grid's SubscriptionValidationEvent (answered with its validationResponse), and Trello's HEAD check (the head operation of this url).

A handshake writes no card data, is never billed and spends no rate budget, and is recorded in the delivery log with outcome handshake.

The body, at most 1 MiB, is JSON, application/x-www-form-urlencoded (a repeated name is an array) or multipart/form-data (each text field is body.<field>, a repeated name is an array, and file parts are ignored and counted in the delivery log). With no mapping the object is the document; with one, the template builds it from body and query.

The document is checked as the card's data (card_data_invalid names the path), and one equal to the current document is not written (status unchanged). An accepted post is one billed API request and appends the card data events. Idempotency-Key (8 to 200 characters) deduplicates a sender's retries for twenty-four hours.

At most 120 posts per minute per webhook; each also counts toward the organization's and the card's write rates (PUT /api/card-data/{key}).

The check Trello makes of a new webhook. It answers 200 with no body for a webhook whose handshake is trello, and the one 404 not_found for every other webhook, address and request, so a link previewer learns nothing. It writes nothing, is never billed and spends no rate budget; the answered check is in the delivery log with outcome handshake.

Every GET answers the 404 and reads nothing.

Lists the project's card data documents, at most 200 in ascending key order. next_cursor is the last returned key; pass it back as after for the next page, null when there are no more. Card data documents hold the dynamic properties of card placements (menu sections, ticker items, KPI tiles); the placement's data key names one.

Returns the document and its revision. ETag is the revision, for If-Match on the next write.

Creates or replaces a card data document. When card placements in the project's playlists bind the key, the document must hold only each bound card's dynamic properties and validate against them; otherwise the write is refused with card_data_invalid naming the card and the property path, and nothing changes. A key no placement binds accepts any JSON object.

Every string that begins with media: is a media reference, media:<id>, for a card to draw (a photo); on any key it must name a ready, approved image in this project, at most 256 distinct media per document, or the write is refused with card_media_invalid naming the property path and media_id.

Screens whose content reads the key may then fetch those media from GET /media/{media_id}. Screens showing a placement that reads the key receive screen.card_data_changed and refetch it in place; the project log records kv.updated with a card_data_entry resource, which never reaches a Player.

Limits, quota, metering, revisions and idempotency are the application K/V store's.

Agent and webhook writes are also rate limited, per organization by plan (Standard and Plus 60 a minute, Education and Premium 600, Enterprise 3,000) and to 60 a minute per key on every plan; a write over a limit is refused with rate_limited and Retry-After, and is not metered.

Deletes a card data document. A card bound to the key is hidden on glass until a document is written again.

Reads a shared third-party feed document: the same document a built-in card placement with the same params reads (docs/feeds.md).

Query parameters normalize into the card's feed key, named by the ScreenRig-Feed-Key header: weather, airquality and alerts take lat and lon (rounded to a 0.25 degree cell); earthquakes lat, lon, radius_km (10 to 20000, default 500), min_magnitude (0 to 9, default 2.5) and hours (1 to 168, default 24); cyclones basins (comma separated at, ep, cp, wp; default all) and optionally lat, lon and radius_km (the storms near that place); tides station (a NOAA tide prediction station id such as 9414290) or lat and lon (the nearest station within 100 km, else invalid_request); launches no parameters (the next launches worldwide); rates base (an ECB reference currency, default EUR); crypto symbols (CoinGecko ids or tickers, comma separated, at most 20) and currency (default usd); headlines url (an http or https RSS or Atom URL); cap (screenrig.cap/v1) the CAP alerts matching a screen: url (repeatable, up to 5 CAP alert or ATOM/RSS index URLs), public (also read the public feeds covering lat and lon; default when no url), lat and lon, geocode (repeatable NAME:VALUE area codes), min_severity, max_severity, min_urgency, min_certainty, event, exclude_event, sender, status (default Actual), scope (default Public), language (repeatable, in preference order) and area_unknown (hide or show); drugalerts (screenrig.drugalerts/v1) the recent recall reports of a country: country (us, ca or gb, required) and category (drug, the default, or food); respiratory (screenrig.respiratory/v1) the weekly flu, COVID-19 and RSV activity of a place: country (us or gb, required) and region (a US state, territory or DC by name or postal code, or England or a UKHSA region; the nation when empty); almanac (screenrig.almanac/v1) the observances, On This Day events, sun and moon of a date for the today card: country (an ISO 3166-1 alpha-2 code, for its public holidays), language (an On This Day edition: ar, bs, cs, de, en, es, fr, it, pt, ru, sv, tr, uk or zh; default en), optionally lat and lon (rounded to a 0.1 degree cell, for the sun) and date (a fixed day; default the days around today); outdoorsafety (screenrig.outdoorsafety/v1) the heat for the outdoor-safety card, an estimate of the wet bulb globe temperature, from lat and lon (the weather's 0.25 degree cell); it reports no lightning; departures (screenrig.departures/v1) the next departures at one to four stops of one open-data provider: provider (tfl, entur or digitransit) and stops (comma separated ids, at most 4: TfL StopPoint ids, Entur NSR stop place or quay ids, Digitransit gtfsIds), merged into one board in leaving order and polled every minute; bikeshare (screenrig.bikeshare/v1) the GBFS bike share stations nearest lat and lon (rounded to a 0.001 degree cell, about 100 m), each with its distance from that cell, from system (a listed system id) or, without it, the nearest listed system that covers the place (invalid_request at system where none does).

The request never calls the provider. 200 is the document (schema, fetchedAt, attribution and the family's fields, as the cards contract defines them); its ETag is the sha256 of the bytes and If-None-Match answers 304; Cache-Control max-age runs to the next scheduled fetch. 202 means no document yet: the read registered demand, and the feed worker fetches the key within about a minute (Retry-After).

An API read keeps a key fetched for 24 hours. An organization registers at most 50 new keys a day across its projects (rate_limited past it). A family with no source on this deployment answers not_found.