Config options
| Option | Default | Meaning |
|---|---|---|
visibility.default | private | The level an upload gets when it names none. Must be one of allowed |
visibility.allowed | all three | The levels a write may name. ["private", "organization"] means nothing can ever be public |
dedup.scope | tenant | How far duplicate detection looks: the organization in force, or the owner when none is. account is every record in the account |
delivery.signedUrlTtlSeconds | 3600 | How long a signed delivery URL for a non-public record stays valid. It cannot be revoked, only outlived |
delivery.r2PublicBaseUrl | none | A public bucket’s base URL. Refused unless visibility.allowed is ["public"], because a public bucket serves every key in it |
permission | none | A hook asked on every record read and write: allow, deny or default |
recordStore | d1 | The only value. Records live in D1 |
| Enrichment toggles | off | Alt text, transcription, text extraction — each independent |
| Backend per type | — | Which store handles images, video, audio and documents |
recordStore: 'kv' is refused at boot, by name. The KV record store was removed, because ownership, scoped dedup and per-owner rollups are all queries it could not answer. A Worker that still names it is told to remove it and migrate each environment, rather than booting against an empty record table. kvMetadata is refused the same way.
A level outside allowed is refused, never coerced. Narrowing allowed never rewrites a record either: making a public file private breaks every link already published. pithy doctor names each record the policy no longer admits, and moving it is yours to do with PATCH /media/:id.
Bindings
| Binding | Type | Written by |
|---|---|---|
DB | d1 | pithy add |
MEDIA_BUCKET | r2 | pithy add |
MEDIA_IMAGE_TO_TEXT | workflow, optional | pithy media provision |
MEDIA_AUDIO_TRANSCRIBE | workflow, optional | pithy media provision |
| The video Workflow | workflow, optional | pithy media provision |
The Workflow bindings are declared optional so an app still boots before provisioning has deployed the host — which is what makes a first pithy dev work on a project that has never reached an account.
Secrets
One of these is read by storage, not by media.
Two credentials, because there are two owners, and two signing keys.
| Secret | Belongs to |
|---|---|
media-storage-credentials | Media’s own: the account id the assets live in, and nothing else |
media-r2-credentials | The object store media presigns through — and whose key pair media never sees |
media-images-signing-key | The account’s Images URL-signing key, which signs a private image’s delivery URL |
media-stream-signing-key | A Stream signing key, which signs a private video’s playback URL |
The R2 key pair is not minted. There is no API for creating an S3 access-key pair, so you make it by hand. The signing keys are the opposite: provisioning reads the Images key, or creates one, and creates the Stream key, wherever some record could be private.
Media holds no Cloudflare API token of its own. It reads the application’s one runtime token through the RUNTIME_CF_API_TOKEN binding, and declares what it needs from it as runtimePermissions: images:write while images are in Cloudflare Images, stream:write while video is in Stream, and analytics:read while either is, for the delivery read. A project storing both in R2 calls Cloudflare for nothing and binds no token.
Backends per type
Why each type resolves the way it does is a backend per media type; the calls are in Using Media; standing them up is pithy media.
| Type | Typically |
|---|---|
| Image | The image store, for variants and transformation |
| Video | The streaming store, for adaptive playback |
| Audio, documents | R2, through the object-store seam |
Ownership is metadata, not a name
An asset in the image or video store is keyed by an id the store mints, so there is no name to put a project segment into.
Every asset is stamped with the project and the environment, the same two keys in both stores, so one query answers what does this project own across them.
The stamp is merged last, so a caller’s own metadata cannot displace it. A Worker that cannot name its project refuses to mint.
Who may read a record
The project and environment stamp says which app owns an asset. The record says which person and which organization do: every row carries ownerId and organizationId, from the caller and the organization in force at the write, and null for a system-owned record. Records written before these columns existed are private and system-owned.
| Level | Who reads the record, and learns it exists |
|---|---|
private | The owner, acting for the organization the record was written under. Acting for another organization, not even them |
organization | Any member of the record’s organization, acting for it |
public | Anyone holding the id or URL, signed in or not |
A record the caller may not read is not found, never forbidden, on every route, so an id cannot be probed. organization with no organization in force is refused at the write.
| Route | Who |
|---|---|
POST /media | Any signed-in caller. The record is theirs, in the organization in force. Where payments enforces the mediaItems meter, a create past the caller’s quota is payments/quota_exceeded (402) |
GET /media | The caller’s own records and their organization’s, newest first. includePublic=true adds every public record |
GET /media/:id, GET /media/:id/url | Anyone the record is visible to. A public record needs no credential |
PATCH /media/:id, DELETE /media/:id, POST /media/:id/finalize | The owner, or a role holding media:manage in the record’s organization |
POST /media/duplicates | Any signed-in caller, matched only within dedup.scope |
GET /media/:id/url is how a non-public file is delivered. It answers a short-lived signed URL for a caller who may read the record, and a plain one for a public record. A visibility change to or from public changes Cloudflare’s signing setting too, and one that Cloudflare has not confirmed comes back with signingPending: send it again to finish it.
The permission hook answers allow, deny or default for every record read and write, with the action, the record and the caller. Sharing with one person is an allow; a legal hold is a deny. On a list, a deny removes the row and an allow adds none, so a page can come back short. The hook governs the record routes only: duplicate detection and the usage rollups keep their scoping whatever it answers.
What it does not inherit from storage
It presigns through the object-store seam, against its own bucket and credential name — and inherits none of that capability’s tables, routes, quotas or share links.
So composing both gives you two independent products rather than one with two front doors.
Peer capabilities
Required: secrets.
Optional: auth — effectively required, since an upload belongs to somebody. organization — records then carry the organization in force, and some role must hold media:manage, or the Worker is refused at compose. payments — with its mediaItems meter enforced, the caller’s plan caps how many records they hold, the organization’s under organization billing; see tiers, quotas and features.
Composes naturally with vector, whose corpus is the obvious destination for extracted text.
Provisioning
pithy media provision creates the bucket, writes both credential secrets and, while some record could be private, the two signing keys, and deploys the host that runs the enrichment Workflows.
Each environment’s deploy needs the app database id and that environment’s secrets database, and both are refused rather than deployed around.