public-share

Get Shared Clip

Serve one event's clip to whoever holds a live share link.

UNAUTHENTICATED BY DESIGN. The recipient is a property contact with no console login; the 43-character token IS the capability, and it was minted inside an audited send by a named operator. Nothing here reads a bearer, and enforce_read_only_guardrail does not answer it either -- that guard returns immediately for safe methods, so the view-counter write the service makes inside this GET is invisible to it and needs no allowlist entry.

EVERY NEGATIVE OUTCOME IS THE SAME 404, WITH THE SAME BODY: a malformed token, an unknown hash, an expired link, a revoked link, a retired site, and a missing camera or site row. Distinguishing any two of them hands a scanner an oracle -- which is why serve_public_clip answers one None for all of them rather than an exception per cause.

NOTHING IS LOGGED ON A MISS, beyond whatever the limiter does. A scanner must not be able to fill CloudWatch. A served hit logs the LINK ID and the EVENT ID -- never the token, never a presigned URL. Both live in the service, with the read they describe.

THE TWO PRE-CHECKS BELOW STAY IN THE ROUTER because they are PURE: they touch no DB and no AWS, and their whole value is being cheap enough that a scanner's guess costs nothing. Everything with a side effect is in app/services/share_link_read_service.py (Greptile G4).

THE FEATURE-DARK CHECK RUNS FIRST, before the token-syntax check and before any DB work (round-2 review C2). SHARE_LINK_BASE_URL can be unset AFTER links already exist -- an ops rollback, a task-definition edit -- and without this check a still-valid link would keep serving even though mint() now refuses every new one and GET /telephony/ config reports the feature dark. Same 404, same body: this must not be a fourth distinguishable outcome.

get/public/share/{token}

Request

  • Base URL
    https://api.verdun.ai (the document declares no server; this is the origin it was published from)
  • URL
    https://api.verdun.ai/public/share/{token}
  • Auth
    none declared

Path parameters

tokenstring required

Response

Successful Response

site_namestring nullable

The site's display name -- the recipient's own premises.

camera_labelstring required

The camera's display label. NEVER the stream key, the device id or anything RTSP.

occurred_atstring date-time required

When the motion happened (the event's occurred_at, else its created_at), UTC.

timezonestring nullable

The site's IANA timezone, so the page can render local time.

clip_urlstring nullable

Presigned GET for the clip, SHARE_LINK_CLIP_URL_TTL_SECONDS (default 900). Null when the presign failed; the page then says the clip is unavailable.

poster_urlstring nullable

Presigned GET for the poster frame, same TTL. Null when no poster key derives from the clip key or the presign failed.

expires_atstring date-time required

When this link stops working, so the page can say so.

brand_namestring nullable

The monitoring dealer's customer-facing name, present ONLY when that dealer turned its branding on (white-label). Null means the page is Verdun-branded. A name the dealer chose to show its own customers, never the internal client record.

brand_logo_urlstring nullable

Presigned GET for the dealer's logo (PNG), same TTL as the clip. Null when branding is off, no logo is saved, or the presign failed.

Example response

{
  "timezone": "America/Los_Angeles",
  "brand_name": "Weiser Security Services"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.