---
title: "Get Shared Clip"
method: GET
path: "/public/share/{token}"
tags: ["public-share"]
---

# Get Shared Clip

`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

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.

## Path parameters

- `token` string, required

## Response `200`

Successful Response

- PublicSharedClip: The ONLY body `GET /public/share/{token}` ever returns on a live link. NINE KEYS, NO IDS OF ANY KIND. The holder of this link is an unauthenticated member of the public who happens to have been texted it, so the page reveals the minimum that makes the clip meaningful: whose premises, which camera, when, and the video. No contact name, no operator name, no AI rationale, no vendor string, no parent/client name (the opt-in white-label `brand_name` is the dealer's chosen display name, not the client record), no other events, and nothing that could be replayed against another endpoint. It lives beside the operator-facing share-link models on purpose: the whole contract for this feature is one file, so a field added to the public shape cannot be reviewed without the operator shapes in view.
  - `site_name` string, nullable: The site's display name -- the recipient's own premises.
  - `camera_label` string, required: The camera's display label. NEVER the stream key, the device id or anything RTSP.
  - `occurred_at` string, date-time, required: When the motion happened (the event's `occurred_at`, else its `created_at`), UTC.
  - `timezone` string, nullable: The site's IANA timezone, so the page can render local time.
  - `clip_url` string, 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_url` string, nullable: Presigned GET for the poster frame, same TTL. Null when no poster key derives from the clip key or the presign failed.
  - `expires_at` string, date-time, required: When this link stops working, so the page can say so.
  - `brand_name` string, 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_url` string, 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.

## Other responses

- `404`: Unknown, expired, revoked or malformed link
- `422`: Validation Error

---

[API](https://skmtc.dev/verdun/apis/verdun-api.md) - [All operations](https://skmtc.dev/verdun/apis/verdun-api/llms.txt) - [OpenAPI document](https://skmtc.dev/verdun/apis/verdun-api/revisions/00252d8227c1?raw)