Resolve a public share token to its read-only payload
Atomically claims one use of the token and returns a read-only render of the shared item: a surface's manifest and blocks, or a file's name, type, size, and inline capability URL, each with a minimal meta block carrying the title, access level, and workspace name. No authentication; the share token in the path is the credential. A revoked, expired, or use-exhausted token — and an item that is archived or not publicly renderable — all return the same opaque not-found response.
curl -X GET "https://example.com/v1/public/shares/string"{ "data": { "type": "surface", "meta": { "kind": "folder", "title": "string", "icon": "string", "color": "string", "allowDownload": true, "accessLevel": "view", "workspaceName": "string" }, "surfaceId": "string", "surfaceKind": "string", "manifest": {}, "blocks": [ { "id": "string", "workspaceId": "string", "surfaceId": "string", "parentBlockId": "string", "kind": "paragraph", "orderKey": "string", "manifest": {}, "layout": { "x": 0, "y": 0, "w": 0, "h": 0, "tab": "string" }, "plainText": "string", "createdAt": "string", "updatedAt": "string" } ], "hasMore": true }}{ "_tag": "ApiNotFound", "error": "not_found", "message": "That item does not exist, or this key cannot see it.", "status": 404}{ "_tag": "ApiNotFound", "error": "not_found", "message": "That item does not exist, or this key cannot see it.", "status": 404}Claim a share token as the signed-in user
Validates an unrevoked, unexpired token without consuming a use, then persists a durable guest grant at the link's access level so the item stays reachable afterward and shows up in shared-with-me, and returns the item, its workspace, and the granted level (plus the public payload when the item is a file). Requires a Clerk session; API keys are rejected. Every invalid, expired, revoked, or exhausted token returns the same opaque not-found response.
Comment on a shared page through a share link
Adds a comment to one block of a shared page or note on behalf of an anonymous guest, attributed with the optional `guestName`; the block must belong to the shared surface and the body is trimmed to 4000 characters. Resolving the link here does not consume a use, so commenting is repeatable. No authentication; the share token in the path is the credential, and it must grant comment or edit access — anything else returns the same opaque not-found response.