---
title: "Create a public link that opens every file in a folder"
method: POST
path: "/v1/assets/folders/{folder_id}/share-links"
tags: ["assets"]
---

# Create a public link that opens every file in a folder

`POST /v1/assets/folders/{folder_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/folders/{folder_id}/share-links`
- Auth: HTTP bearer

Mint a folder link: every LIVE file in it becomes readable through the link, and every file filed into it afterward joins automatically. Needs the same authority as publishing each file in it today (its author, or an admin) — refused with no count and no names when the caller cannot publish every file. Behind the asset_folder_sharing_enabled kill switch.

## Path parameters

- `folder_id` string, uuid, required: The folder's id.

## Headers

- `X-Tenant-Id` string, nullable

## Request body

- AssetFolderShareLinkCreate: How long a new share link should last, and whether asking may move an open one's deadline. ``expires_in_days`` carries THREE distinct requests, and the difference between two of them is the guard rather than a nicety: omitting the field asks for the default life, sending a number asks for that many days, and sending ``null`` asks for a link with NO end date. An omitted field can therefore never become a never-expiring link — a caller has to name that state to get it. ``refresh_deadline`` separates two acts this one route serves. Publishing a file is a decision about reach and may push its link's deadline outward; asking for the file's address is a read and must not. The field defaults to the publishing behaviour, so no existing caller changes, and a surface that only wants the URL back sends ``false``. Without it such a surface extends a live capability on every press, invisibly, because nobody treats "what is the URL" as a decision.
  - `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.

## Response `201`

Successful Response

- AssetFolderShareLinkCreated: A freshly minted folder link, token included — the ONLY response that ever carries it.
  - `id` string, uuid, required
  - `token` string, required: The capability. Shown once; the server stores only its hash.
  - `url` string, required: The full share URL, ready to copy. Opens the folder's public page.
  - `created_at` string, date-time, required
  - `expires_at` string, date-time, nullable

## 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)