--- title: "Create the file's link" method: POST path: "/v1/assets/{asset_id}/share-links" tags: ["assets"] --- # Create the file's link `POST /v1/assets/{asset_id}/share-links` ## 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/assets/{asset_id}/share-links` - Auth: HTTP bearer Mint the file's link. It is the file's ADDRESS and publishes nothing: who can open it stays whatever the file is set to, checked every time somebody opens it. A file set to 'Only me' gets a link only its author can open; a file set to 'My team' opens for members of this workspace after they sign in; a file set to 'Anyone with the link' opens for anybody with no sign-in. ONE exception, and it is about the FOLDER rather than the file: a file whose folder holds a live folder link is readable by anybody holding that folder's link, whatever the file's own level says, so `asset_visibility` on this answer can read 'private' for a file a stranger can already open. Change who can see a file on PUT /assets/{id}/visibility, which is a separate act with its own permission. The link shows the file's CURRENT version and works until it EXPIRES, is revoked, or the file is deleted (deleting revokes it, so a restore does not bring it back). A new link lasts 30 days unless the body says otherwise. Send `expires_in_days: null` for a link with NO end date, for something meant to stay reachable (a report linked from a website, a deck in a proposal); it still stops the moment anyone revokes it, deletes the file, or sets the file to 'Only me', and a revoked link never comes back. Asking again for a file YOU already have an open link for returns that same link and the same token (`reused: true`) instead of a second URL, so one link can be handed out once and go on serving the file's latest version; it consumes no new link slot, and its end date only ever moves further out, never nearer, and only when you are the file's author or a workspace admin or the file is already 'Anyone with the link'; otherwise the link comes back unchanged and `deadline_moved` is false. Reuse also requires the file's level to equal the recorded mint level, so a publish returns an external-minted URL. A team-minted URL is never reused for that publish. The recorded level also supplies the folder-share bound. Each existing live link follows the file's CURRENT visibility: widening opens existing links to anyone the file allows, and narrowing closes direct outside reads immediately. An external-minted file token can still open through a folder with a live folder link. Revoked and expired links stay closed; password-protected links still require their grant. Folder-share access keeps the token's minted-level bound, so a team-minted file token cannot open through somebody else's folder share. Reuse is per PERSON: it returns the link you created, so a colleague asking for the same file gets their own, and a caller with no actor on their membership always gets a new one. A revoked or expired link is never reused — minting again after either produces a new URL, and the closed one stays closed. The token is shown in API responses only; the server stores it as a hash plus an encrypted copy that only your own later ask can read, so revoke and mint again to get a DIFFERENT URL. Answers 404 when the file does not exist, has been deleted, or belongs to another workspace, or is a private file that is not yours. ## Path parameters - `asset_id` string, uuid, required: The asset's id. ## Headers - `X-Tenant-Id` string, nullable ## Request body - AssetShareLinkCreate: The file mint body: omit expiry for the default life, or send null for no end date. refresh_deadline decides whether reuse may extend a working link's deadline. An optional password protects the new link and creates a separate link outside reuse. - `expires_in_days` integer, nullable: How many days the link works for, from now. Defaults to 30, and a chosen number must be between 1 and 365. Send null for a link with no end date, which then works until somebody turns it off, the file is deleted, or the file is set to 'Only me'. Each of those three REVOKES it, so none of them can be undone by re-sharing the file. - `refresh_deadline` boolean: Whether handing back a link this caller already has open may move its end date outward. True, the default, is a republish: the deadline moves to whichever of the two dates is later, never inward. Moving it is the file author's or a workspace admin's act unless the file is already 'Anyone with the link'; anyone else gets their link back unchanged, and `deadline_moved` in the response says which happened. Send false when the request is only for the file's address, so reading a URL cannot keep a capability alive by being asked for. It changes nothing when there is no link to hand back; one is minted either way. This body serves the FOLDER mint too, which has nothing to hand back: a folder link is always a new row, so the field does not apply there and that route ignores it. - `password` string, nullable: An optional password, at most 72 UTF-8 bytes. ## Response `201` Successful Response - AssetShareLinkCreated: The file's share link, token included — the ONLY response that ever carries it. Not always a FRESH link: publishing a file that this person already has an open link for hands that same link back, so the URL a recipient holds keeps working and keeps showing the current version. ``reused`` is how a caller tells the two apart. - `password_protected` boolean, required - `id` string, uuid, required - `token` string, required: The capability, returned in API responses only. The server stores it as a hash plus an encrypted copy that only this person's own republish can read. A republish that reuses the link returns this same token; it is not a one-time value. - `url` string, required: The full share URL, ready to copy. An eligible published HTML site opens on sites.patricia.app. Other files open the console recipient page with file details and a download button. The file's visibility and link password determine access. - `created_at` string, date-time, required - `expires_at` string, date-time, nullable: When this link stops working. Null when it was created with no end date, which only happens when the request asked for one. - `asset_visibility` 'private' | 'team' | 'external': The file's visibility AFTER the mint, which is always 'external': publishing a file is what decides its audience, so minting a link for a file below that level raises it. Returned so a caller can show the new level without re-reading the file. - `reused` boolean: True when this is the link you already had for this file rather than a new one. Publishing a file you have an open link for returns that link, and its end date only moves further out, so one URL keeps serving the file's latest version. Reuse is per person: it finds the link YOU created. False means a link was created — the file had none of yours, the one it had was revoked or has expired, or your membership carries no actor for a link to be recorded against. - `deadline_moved` boolean: True when this call moved the link's end date further out. False for a new link (its date was set, not moved), for a request with refresh_deadline false, for a republish of a link whose date was already the later one, and for a republish by someone who is not the file's author or a workspace admin on a file that is not 'Anyone with the link': that link comes back unchanged, and only the author or an admin can extend it. ## Other responses - `400`: Bad request - `401`: Unauthorized - `403`: Forbidden. Inspect response body `code` for the specific reason (for example: PERMISSION_DENIED, EMAIL_NOT_VERIFIED, TENANT_ACCESS_REQUIRED, ROLE_UNRESOLVED) - `409`: Conflict - `422`: Validation error --- [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)