--- title: "What one share link opens (public, by capability token)" method: GET path: "/v1/shared-assets/{token}/meta" tags: ["shared-assets"] --- # What one share link opens (public, by capability token) `GET /v1/shared-assets/{token}/meta` ## Request - Base URL: `https://api.patricia.app` (the document declares no server; this is the origin it was published from) - URL: `https://api.patricia.app/v1/shared-assets/{token}/meta` - Auth: one of: - HTTP bearer - none The facts about the file behind one share link: its name, type, size, when it was made, who made it, and when the link stops working. A sign-in is optional and never required: send one and a member of the file's workspace is also told who can see it and whether they may change that. Carries nothing about the workspace the file came from and nothing about any other file. Answers 404 for an unknown, revoked or expired link, for a deleted file, and for a file this reader may not see, indistinguishably. ## Path parameters - `token` string, required: The share link's capability token. ## Query parameters - `access_acknowledgement` string, uuid, nullable: A UUID for one deliberate private-file opening. Reuse across requests for the same opening. ## Headers - `X-Share-Grant` string, nullable ## Response `200` Successful Response - SharedAssetView: One shared file as its READER sees it — the capability-scoped shape behind ``/shared/``. Everything a page needs to show the file honestly, and nothing that describes the workspace it came from. There is no tenant, no folder, no version history and no sibling here, because the token addresses ONE file: a field that named anything else would be describing something the holder was never handed. Members receive ``visibility``, ``can_change_visibility`` and ``asset_id`` with values for their access. Outside readers receive these three fields as ``null``, ``false`` and ``null``. Members also receive ``is_owner`` and ``requires_access_acknowledgement``. The server omits both fields for outside readers. These fields tell members whose file they see and whether opening it requires a recorded acknowledgement. The server decides whether the page offers the visibility control through ``can_change_visibility``. The ``PUT /assets/{id}/visibility`` route checks the same authority. ``name`` is UNTRUSTED text, exactly as it is on the authenticated surface — an agent run names an asset. It goes out as a plain JSON string and the page renders it as text, never as markup. - `is_owner` boolean: Whether the signed-in caller owns this file. - `requires_access_acknowledgement` boolean: Whether content requires an access_acknowledgement UUID and a durable audit receipt. - `name` string, required: The file's name. UNTRUSTED text: render escaped. - `category` 'document' | 'media' | 'app', required: Which library it came from: 'document' or 'media'. - `kind` 'app' | 'audio' | 'docx' | 'file' | 'html' | 'image' | 'markdown' | 'pdf' | 'slides' | 'spreadsheet' | 'video', required: What sort of file this is, for the icon and the preview. - `content_type` string, required: The current version's media type, e.g. 'application/pdf'. - `byte_size` integer, required: The current version's size in bytes. - `created_at` string, date-time, required: When the file was made (UTC). - `updated_at` string, date-time, required: When the file last changed (UTC). - `author` SharedAssetAuthor: Who made a shared file, for the person the link was sent to. Deliberately NOT :class:`AssetAuthor`, and the missing field is the whole point: this shape has no ``actor_id`` to fill, so the public surface cannot carry a workspace member's identifier however it is later edited. A name is what "who sent me this" wants; an id addresses nothing a recipient can open and everything a scraper would like. - `display_name` string, nullable: The name of the person who made the file. Null when nothing resolves. - `made_by_patricia` boolean: Whether a Patricia run created this file. True with a display_name reads 'Patricia for '; true without one reads 'Patricia'; false reads the name alone. - `expires_at` string, date-time, nullable: When this link stops working, so the page can say so before the file goes. Null only for a link minted before share links carried a deadline. - `thumbnail_status` 'ready' | 'pending' | 'unavailable': Whether a preview image exists for this file. 'ready' means GET /shared-assets/{token}/thumbnail serves it; 'pending' means one is being prepared, ask again shortly; 'unavailable' means the type icon is the answer. - `visibility` 'private' | 'team' | 'external', nullable: Who can open this file, so the page can say so. Answered only for a signed-in member of the workspace that owns it; null for anyone else, because who else can read a file is not a stranger's business. - `can_change_visibility` boolean: Whether YOU may change who can see this file from this page. True only when every condition PUT /assets/{id}/visibility checks for itself already holds: you are a member of this file's workspace, your session is signed in to THAT workspace, your role carries assets:edit, and you added the file or are a workspace admin. False for anyone else, so a control enabled by this flag is never refused by that request. - `asset_id` string, uuid, nullable: This file's id, for the PUT /assets/{id}/visibility call the control above makes. Null for anyone who is not a signed-in member of the workspace that owns it. ## Other responses - `401`: A password grant is required. - `404`: No shared file for that link. - `422`: Validation Error - `429`: The address request ceiling is reached. - `503`: PRIVATE_ASSET_AUDIT_UNAVAILABLE: access cannot be recorded. --- [API](https://skmtc.dev/patricia/apis/patricia-api.md) · [All operations](https://skmtc.dev/patricia/apis/patricia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/patricia/apis/patricia-api/revisions/0dfb44495ea1?raw)