Media reference

Config options

OptionDefaultMeaning
visibility.defaultprivateThe level an upload gets when it names none. Must be one of allowed
visibility.allowedall threeThe levels a write may name. ["private", "organization"] means nothing can ever be public
dedup.scopetenantHow far duplicate detection looks: the organization in force, or the owner when none is. account is every record in the account
delivery.signedUrlTtlSeconds3600How long a signed delivery URL for a non-public record stays valid. It cannot be revoked, only outlived
delivery.r2PublicBaseUrlnoneA public bucket’s base URL. Refused unless visibility.allowed is ["public"], because a public bucket serves every key in it
permissionnoneA hook asked on every record read and write: allow, deny or default
recordStored1The only value. Records live in D1
Enrichment togglesoffAlt 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

BindingTypeWritten by
DBd1pithy add
MEDIA_BUCKETr2pithy add
MEDIA_IMAGE_TO_TEXTworkflow, optionalpithy media provision
MEDIA_AUDIO_TRANSCRIBEworkflow, optionalpithy media provision
The video Workflowworkflow, optionalpithy 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.

SecretBelongs to
media-storage-credentialsMedia’s own: the account id the assets live in, and nothing else
media-r2-credentialsThe object store media presigns through — and whose key pair media never sees
media-images-signing-keyThe account’s Images URL-signing key, which signs a private image’s delivery URL
media-stream-signing-keyA 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.

TypeTypically
ImageThe image store, for variants and transformation
VideoThe streaming store, for adaptive playback
Audio, documentsR2, 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.

LevelWho reads the record, and learns it exists
privateThe owner, acting for the organization the record was written under. Acting for another organization, not even them
organizationAny member of the record’s organization, acting for it
publicAnyone 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.

RouteWho
POST /mediaAny 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 /mediaThe caller’s own records and their organization’s, newest first. includePublic=true adds every public record
GET /media/:id, GET /media/:id/urlAnyone the record is visible to. A public record needs no credential
PATCH /media/:id, DELETE /media/:id, POST /media/:id/finalizeThe owner, or a role holding media:manage in the record’s organization
POST /media/duplicatesAny 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.

ESC