Return the schema.request entry for one operation name (from schema.get.operations).

List thirdparty-v1 operation names and required OAuth scopes (compact).

Health/auth sanity check for the current access token.

Returns this API schema contract for tooling and bots.

Set is_archived=true on an owned collection (hidden from default lists).

Fetch up to 30 collections by id in one call (owned, non-deleted only). Order matches the request ids where possible.

Create a new collection owned by the token subject. If thumbnail_url is http(s), the image is downloaded to R2; raster images are processed through the same GCF image pipeline as media uploads (WebP main + thumbnail on the media table, then the collection stores the resulting r2:// thumbnail). When parent_collection_id is set, creates a sub-collection (is_subcollection=true) and inserts the inline subcollection stub media row in the parent collection (requires media:write in addition to collections:write).

Delete an owned collection: soft (is_deleted) by default; hard removes the row (DB cascades media). Non-empty soft-delete requires cascade_media or hard mode.

Export one owned collection’s media metadata as JSON or CSV (no binary file bodies; use media.download per item for R2 content).

Fetch one collection by id when the token subject owns it or is an accepted collaborator.

Resolve a collection from its public URL handle and slug (www.zegazone.com/{handle}/{slug}). Returns the row when the collection is public/registered or the caller has read access.

Mint a presigned R2 PUT URL for a collection cover image only (purpose=cover). IMPORTANT: The presigned PUT requires direct network access to r2.cloudflarestorage.com — sandboxed agents may not be able to reach R2. After PUT, set collections.update thumbnail_url to the returned r2_key. Do NOT use this for media item thumbnails — use media.get_upload_url with purpose=thumbnail, then media.thumbnail_finalize.

List collections owned by the token subject. With parent_collection_id, returns only that collection’s sub-collections.

Publish an owned collection (share_access_level=public, set share_slug).

Assign collection position order by explicit ordered_ids (subset of owned non-deleted collections).

Restore an owned soft-deleted collection (is_deleted = false).

Get the public share URL for a published collection (www.zegazone.com/{handle}/{slug}).

Set is_archived=false on an owned collection.

Make an owned collection private.

Update one owned collection in place. Only provided fields are changed; optional thumbnail_url can be ingested into R2 like collections.create.

Set is_archived=true on owned media.

List media across multiple owned collections in one request (max 30 ids). Supports the same limit/offset as media.list on the combined result set.

Duplicate one owned media row into another owned collection (same URLs; new row id).

Create a media row in a collection where the token subject is owner or has upload permission. viewer controls whether URL is treated as website link or ingested to R2. YouTube/Vimeo URLs are always stored as website links (external embed) even if viewer is video. Website items without thumbnail_url get OG image auto-fetched for carousel thumbnail. Tags: max 10 lowercase strings; when omitted, defaults to []. To mirror the human Add Media UI (collection-tag snapshot), read collection.tags via collections.get and pass them explicitly.

Delete media in collections where the token subject is owner or has delete permission: hard (row delete, default, matches in-app) or soft (is_deleted). Batch via media_ids.

Return full metadata for one readable media item, including resolved proxy URLs and inferred viewer information. Proxy URLs require Zegazone bearer auth — use media.download_url for a fetchable URL.

Download private R2-backed media bytes with OAuth bearer auth.

Mint a short-lived proxied download URL on api.zegaphone.com for a readable media item. Token is embedded in the URL — no bearer auth required for fetch.

Fetch one media row by id when the token subject can read its parent collection.

Mint a presigned R2 PUT URL for uploading file bytes directly (agents/MCP). IMPORTANT: The presigned PUT requires direct network access to r2.cloudflarestorage.com — sandboxed agents may not be able to reach R2. For sandboxed environments, use media.upload instead (accepts base64 content and performs the R2 PUT server-side). After PUT with purpose=thumbnail, set thumbnail_url on the media row then call media.thumbnail_finalize to GCF-resize (200px thumb + 800px background). Do NOT use collections.get_upload_url for media thumbnails.

List media rows in accessible collections with optional filters.

Move one or more owned media rows into another owned collection; optional start position.

Renumber positions 0..n-1 for all non-deleted media in one owned collection.

Replace the main content of an owned media item: same ingestion rules as media.create (website = external main_url; otherwise download to R2, raster images run the GCF pipeline). Optional name/type/thumbnail_url updates.

Restore owned soft-deleted media (is_deleted = false).

Search accessible media by name, description, and tags (ILIKE + tag overlap). Optional collection_id scopes to one collection.

Create an inline text-note media row (`text_note` body, `main_url` = inline://text-note). Same storage as app “text note” uploads; no R2 object. Rendering: set `display_mode` (plain|markdown|code) or `viewer` (text|markdown|code); `text` is an alias for plain. If both are sent, they must agree (plain↔text). Set `placeholder_kind` for a semantic carousel icon (defaults to `notes`) or pass `thumbnail_url` for a custom cover.

Delete one owned inline text-note media row (`main_url` = inline://text-note). Destructive: requires confirm:true unless dry_run:true (same gate as media.delete).

Read `text_note` and metadata for one inline text-note media row (`main_url` = inline://text-note). Caller must have read access to the parent collection.

Update `text_note` content (and optional display/name/description) for one owned inline text-note media row. Omitted `display_mode` and `viewer` leave type/viewer unchanged. Same display rules as `media.text_note.add`. Update cover with `thumbnail_url` and/or `placeholder_kind`; omit both to leave thumbnail unchanged.

After uploading raw image bytes via media.get_upload_url (purpose=thumbnail) and setting thumbnail_url on the media row, call this to GCF-resize to 200px WebP carousel thumb + 800px background in R2 and update thumbnail_url + background_image_url. Also runs automatically when media.create/update sets an r2:// thumbnail key.

Deprecated alias for media.thumbnail_finalize. After PUT bytes to media.get_upload_url (purpose=thumbnail), sets thumbnail_url if provided then runs GCF finalize (200px WebP thumb + 800px background). Prefer media.thumbnail_finalize.

Set is_archived=false on owned media.

Update fields on media in collections where the token subject is owner or has edit permission. When thumbnail_url is set to an r2:// key from media.get_upload_url, the server auto-runs media.thumbnail_finalize (GCF 200px thumb + 800px background). After uploading via media.get_upload_url, you must call media.thumbnail_finalize if not setting thumbnail_url here. Do NOT use collections.get_upload_url for media thumbnails.

Upload a file to Zegazone storage via base64 content (sandbox-friendly alternative to media.get_upload_url). Decodes base64 to original bytes, uploads to R2 with correct Content-Type, auto-detects viewer from MIME type, and creates the media row. Returns the created media item. INTEGRITY: content_length is REQUIRED and verified post-decode — if the decoded size does not match, the upload is rejected (catches truncation). Optionally pass sha256 for full hash verification. ENCODING GUIDANCE: Encode content_base64 IN-PROCESS in your runtime (e.g. Buffer.from(bytes).toString("base64") or btoa) — do NOT shell out to bash and capture the encoded string through a tool-result channel, which is slow for non-trivial files and bloats context. The upload itself is instant; if encoding feels slow, it is your local encode/transport, not the server — do not retry the upload. SWEET SPOT: Best for small files and documents (well under 7.5MB decoded). For large media (video, high-res images), use the presigned flow: media.get_upload_url → HTTP PUT → media.create. Max 10MB base64 (≈7.5MB decoded). Preserves byte-for-byte integrity.

Browse collections without a search query. Uses browse_collections_scoped for public/following/liked; own/shared via service-role queries. Scope own/shared need collections:read. Optional tags[] OR-filters by collection tags; sort_by matches browse-collections edge (views, recent, likes).

Search published collections (FTS + trigram). Proxies search_collections_scoped RPC (search-collections edge function). No extra OAuth scope; following/liked scopes need a user-bound token.

Read like/view stats for a collection the caller can access.

Follow another user publish alias (profile_aliases row).

List aliases and primary usernames the token subject follows. Optional limit/offset paginate (returns a pagination block when either is set).

List publish handles (primary username + profile_aliases) for the token subject.

Unfollow a publish alias.

Like a public collection (uses collection_like_set RPC, same as like-collection edge function).

List collections the token subject has liked.

Remove your like from a collection.

Invite a Zegazone user to collaborate on a restricted/private owned collection by username. Rate-capped (ZEG-451): 15/hour, max 20 pending per collection, max 50 sent per 24h; breaching returns 429 rate_limited.

Accept a pending collaboration invite.

Decline a pending collaboration invite.

List pending collaboration invites sent by the token subject.

List pending collaboration invites received by the token subject.

List accepted collaborators on an owned collection.

Remove a collaborator or cancel a pending invite on an owned collection.

Update upload/edit/delete permissions for an existing collaborator or pending invite.

List active global tag vocabulary (slug, label, category, sort_order), ordered by sort_order. Curated list for pickers and agent tagging — distinct from profile custom shortcuts (available_tags, max 20). Collection and media tags are max 10 each.

Get the token subject profile (username, display name, follower counts, bio, aliases, custom tag shortcuts). Response includes available_tags (max 20 lowercase shortcuts for pickers).

Update display_name (profiles.full_name), bio (app_settings.about_you), and/or available_tags (max 20 custom shortcuts).

Return the latest synchronized UI state for the token subject.

Persist and broadcast the active UI selection, player chrome, and agent browse grid for the token subject.

Save a named bookmark of collection ids for later recall in the player.

Delete a bookmark by id.

List collection browse bookmarks saved by the token subject.

Revoke hosted MCP OAuth sessions for the authenticated user (D1 credentials + oauth_refresh_tokens). Accepts third-party access token or first-party Supabase session JWT from zegazone.com settings.