Sharing and public links
Summary
Every file and every folder has a general access setting. It is either "Restricted" - only people who can open its workspace or organization folder - or "Anyone with the link", which is called public.
A public file has one public link. Anyone who has the link opens the file without signing in. The link never changes for that file and always serves the file's current version.
Sharing is strict. A file is public only while three things hold at once: it is live, its status allows public use, and the file itself or a folder above it is shared with "Anyone with the link". When any of the three stops holding, the link stops at once.
Only owners and admins decide what is public, and general access itself is
changed only by a person in a browser. An API key or connected app can read
who can open a file. It can never change the general access setting of a
file or folder. With the scope files:approve it can still start or stop
links through a status change or a move, as described below.
This page covers general access, the strict rule, the public link, public folders and their gallery page, what members see, moves and restores that change who can open files, the warning about location data, and copying links. How the link's bytes are served, cached and resized is described in Image delivery. Statuses are described in Statuses.
Who can do what
In a workspace the role is the effective workspace role. In the organization folder it is the organization role. See Roles and permissions.
| Action | Owner | Admin | Member | Session | Credential (scope) |
|---|---|---|---|---|---|
| See a file's or folder's general access, whether it is public, and its public link | Yes | Yes | Yes | Yes | Yes (files:read) |
| Copy a link | Yes | Yes | Yes | Yes | Not applicable |
| Make a file public or restricted | Yes | Yes | No | Yes | No |
| Make a folder public or restricted | Yes | Yes | No | Yes | No |
| Move a file or folder when nobody's access changes | Yes | Yes | Workspace: yes. Organization folder: no | Yes | Yes (files:write) |
| Move a file or folder so that public links stop | Yes | Yes | Workspace: yes. Organization folder: no | Yes | Yes (files:write) |
| Move a file or folder so that files become public | Yes | Yes | No | Yes | Yes (files:write and files:approve) |
| Restore from the trash what comes back as it was | Yes | Yes | Workspace: yes. Organization folder: no | Yes | Yes (files:write) |
| Restore from the trash so that a file becomes public that was not public when it was trashed | Yes | Yes | No | Yes | Yes (files:write and files:approve) |
| Open a public link or a public folder's gallery | Anyone | Anyone | Anyone | Not needed | Not needed |
- A credential acts for one member. The role columns apply to that member at the moment of each request.
- A credential that makes files public by a move or a restore also needs its member's email address to be verified.
- A credential that calls the operations that set general access gets
403 FORBIDDENwithdetails.reasonSESSION_REQUIRED, whatever its scopes. - Moves and restores that stop public links, or make files public, ask for a confirmation in some cases. See Moves and restores that change access.
How it works
General access
- A file has one of two settings:
restrictedorpublic. The app calls them "Restricted" and "Anyone with the link". The API calls the settingvisibility. - A folder has the same setting, with the same two values.
- Restricted means: only people who can open the file's workspace. For an organization folder file it means every member of the organization.
- Public means: anyone on the internet who has the link, without signing in.
- Every new file and every new folder starts restricted.
- The setting belongs to the file or folder. A new version of a file keeps it. A rename keeps it. A move keeps it.
- General access is the only way to open a file to people outside the organization. There is no sharing with named outside people, no password and no expiry date on a public link.
- Changing general access takes effect at once.
- Changing general access does not change the file's
lockVersionand takes noexpectedLockVersion. - Every change of a file's or folder's general access is recorded in the
audit trail as
file.visibility_changedorfolder.visibility_changed.
The strict rule
A file is public - anyone with its link opens it - only while all of these hold:
- It is live. It is not in the trash, and its workspace and its organization are not deleted.
- Its status allows public use. A file without a status is never public. See Statuses.
- It is shared. The file's own general access is "Anyone with the link", or a live folder at or above it is shared with "Anyone with the link".
What follows from the rule:
- The setting alone is not enough. A file can have the setting
visibility: publicand still not be public, for example while it is in the trash. The API says what is true now inpublic(trueorfalse) and inpublicURL(the link, ornull). - A status that allows public use is not enough either. It only makes a file able to be public. Someone still has to share the file or a folder above it.
- A new upload is never public at once. It starts with the organization's default status or with none, and neither allows public use. This holds even for an upload into a public folder. See The default status.
- When a condition stops holding, the link stops at once. It answers "not found", exactly like a link that never existed.
- Nothing else makes a file public. A suggestion cannot change general access or statuses, and no credential can change general access.
Who changes general access
- Owners and admins change the general access of files and folders. Members cannot.
- For a workspace file or folder, the effective workspace role counts: organization owners and admins, and members who are owner or admin of that workspace.
- For an organization folder file or folder, the organization role counts.
- It needs a person signed in with a browser. No API key or connected app can do it, and there is no MCP tool for it. See What "needs a person in a browser" means.
- A verified email address is not needed in a browser session.
- Everyone who can open the workspace or organization folder can read the setting and copy the link.
Making a file public
- The file must be live and must have a status that allows public use.
- No confirmation is asked. The request is the decision.
- The answer is the file, with
visibilitypublic,publictrueand itspublicURL. - Making public a file that is already set to public succeeds and changes nothing. No audit event is recorded.
The checks happen in this order. The first that fails decides the answer:
- Not signed in:
401 UNAUTHENTICATED. - The request comes from a credential:
403 FORBIDDEN, reasonSESSION_REQUIRED. - The workspace or organization is unknown, deleted or out of your reach:
404 NOT_FOUND. visibilityis missing or is notrestrictedorpublic:422 VALIDATION_FAILED.- You are not an owner or admin:
403 FORBIDDEN. - The file is unknown or belongs to another workspace or organization folder:
404 NOT_FOUND. - The file is in the trash:
409 CONFLICT, reasonIN_TRASH. - The file already has the setting asked for:
200, nothing changes. - The file has no status:
409 CONFLICT, reasonSTATUS_BLOCKS_PUBLIC, with the message "The file has no status; give it one that allows public use first". - The file's status does not allow public use:
409 CONFLICT, reasonSTATUS_BLOCKS_PUBLIC, with the message "The file's status does not allow public use". - Otherwise it is public:
200.
Making a file restricted
- The same people, in the same way, with the same checks 1 to 8.
- A status is not needed to restrict a file.
- The file's own link stops at once, unless a public folder above the file still shares it. In that case the file stays public through the folder. To stop that, restrict the folder or move the file out.
- The link's address is kept. Making the file public again brings the same link back.
The public link
-
A public file's link has this form:
https://files.talewrightusercontent.com/p/3f9c2b7e4a1d4c0e9b8a7f6e5d4c3b2a/logo.png -
It is served from the files host, a separate host from the app. It needs no sign-in and no cookie, and the files host sets no cookie.
-
The middle part is 32 random hexadecimal digits. It identifies the file. It cannot be guessed from the file's name or ID.
-
A file gets this part the first time it becomes public, by any route: shared itself, or through a public folder. It never changes afterwards and cannot be replaced by a new one.
-
So a file has exactly one public link for its whole life. Restricting it and making it public again gives the same link. So does a trash and a restore, a blocking status followed by an allowing one, and a deleted and restored workspace or organization.
-
The last part is the file's name. It is there for people to read. The file is found by the 32 digits alone, so a link with an old name, or with any other name, opens the same file. Renaming a file never breaks its link.
-
In the link the name is percent-encoded: everything except letters, digits,
-,_,.and~. A space is written%20. -
A file saved from the link gets the file's current name, whatever name the link carried.
-
The link always serves the file's current version: the original as it was uploaded, byte for byte. When the file is replaced by a new version, the same link serves the new one. A replacement is always of the same file type, so a link never changes type. See Versions and history.
-
A link cannot be pinned to one version.
-
A link that does not work answers
404 NOT_FOUND. A restricted file, a trashed file, a file blocked by its status, a file of a deleted workspace and a link that never existed all answer exactly the same. Nobody can tell from the answer whether a file exists. -
The "not found" answer is never cached. When the file becomes public again, the link works again at once.
-
A browser that has loaded a public file may reuse its copy for up to 60 seconds. So a change can take up to a minute to show in a browser that had the file open. See Caching.
-
The link also has resized and converted variants for images. They follow the same rule: they work only while the link works. See Image variants.
-
Other websites can embed and read a public link. See Use from other websites.
-
A public link is different from a signed link. A signed link is made for one version, lasts 10 minutes and exists for restricted files too. See Signed links.
What stops a link and what brings it back
| What happens | The link | What brings it back |
|---|---|---|
| The file is made restricted | Stops, unless a public folder still shares the file | Make the file public again. |
| The public folder that shared the file is made restricted | Stops, unless the file is public itself or another public folder is above it | Make the folder public again. |
| The file gets a status that does not allow public use, or its status is cleared | Stops. The file's own setting becomes restricted | Set an allowing status. A link through a folder returns then. The file's own sharing must be turned on again by an owner or admin. |
| The file's status stops allowing public use on the organization's list | Stops for every file with that status. Their own settings become restricted | Allow public use again: links through folders return. Files shared themselves must be shared again. |
| The file's status is deleted | Stops. The file has no status and its own setting becomes restricted | Set an allowing status, then share again where the file was shared itself. |
| The file is moved out of a public folder | Stops, unless the file is public itself or the destination is in a public folder | Move it back, or share the file itself. |
| The file is moved to the trash, alone or with its folder | Stops | Restore it. See Restores. |
| The file's workspace or organization is deleted | Stops | Restore the workspace or organization. |
| The file is deleted for good | Stops for good | Nothing. |
| The file is renamed | Keeps working, old address included | - |
| The file gets a new version | Keeps working and serves the new version | - |
| The file is moved between two public folders, or is public itself | Keeps working | - |
- A blocking status changes the file's own setting to restricted, on purpose. A file never becomes public again by itself only because its status allows public use again.
- Status changes that would make files public through a public folder ask for a confirmation first. See Status changes that change access and Deleting a status.
Public folders
- A folder shared with "Anyone with the link" is a public folder.
- Every file in it, and in every folder below it, is public at its own public link - as long as that file is live and its status allows public use.
- Files that are in the folder but have no status, or a status that does not allow public use, stay restricted. They get no link and are not shown on the gallery page.
- No status is needed to make a folder public. A folder has no status.
- No confirmation is asked when a folder is made public, however many files become public with it.
- Files added to a public folder later follow the same rule. A file moved in becomes public if its status allows it; such a move asks first. An upload into the folder starts with the default status and is not public until an owner or admin gives it an allowing status.
- A file that is public only through a folder keeps its own setting
restricted. The API names the folder that shares it inpublicVia(idandname): the nearest public folder at or above the file. - Restricting a public folder stops the links it gave. A file that is public itself stays public.
- Restricting a subfolder of a public folder changes nothing. The folder above still shares everything below it. To keep part of a public folder private, move it out, or give its files a status that does not allow public use.
- Subfolders of a public folder are public too. Each has its own gallery
page, and its
publicVianames the folder above that shares it. - A folder in the trash shares nothing, and neither does any folder below
it. A trashed folder's general access cannot be changed:
409 CONFLICT, reasonIN_TRASH. - Setting a folder to the value it already has succeeds and changes nothing.
The checks for changing a folder's general access happen in this order:
- Not signed in:
401 UNAUTHENTICATED. - The request comes from a credential:
403 FORBIDDEN, reasonSESSION_REQUIRED. - The workspace or organization is unknown, deleted or out of your reach:
404 NOT_FOUND. visibilityis missing or is notrestrictedorpublic:422 VALIDATION_FAILED.- You are not an owner or admin:
403 FORBIDDEN. - The folder is unknown or belongs to another workspace or organization folder:
404 NOT_FOUND. - The folder is in the trash:
409 CONFLICT, reasonIN_TRASH. - Otherwise the setting is stored:
200with the folder.
The gallery page
-
A public folder has a public page, the gallery. Its address has this form:
https://files.talewrightusercontent.com/p/f/8a1b6c2d3e4f40718293a4b5c6d7e8f9/Press%20kit -
The API gives it as the folder's
publicURLwhile the folder is public, itself or through a folder above. OtherwisepublicURLisnull. -
Like a file's link, it is found by the 32 digits alone. The name at the end is for people, and renaming the folder never breaks the address.
-
Every folder has its address from the moment it is created. It never changes. It works only while the folder is public.
-
The gallery is a page to open in a browser. It is not meant to be embedded in or read by another website.
-
It shows the folder's name, its subfolders, and the public files directly in the folder. Files in subfolders are on the subfolders' own gallery pages.
-
Subfolders come first, then files, each sorted by name without regard to case.
-
It lists at most 1,000 subfolders and at most 1,000 files. Files beyond that are not listed, but each is still public at its own link.
-
Each file shows a thumbnail, its name, its size and a "Download" link. The name and "Download" lead to the file's own public link. The thumbnail is a small variant of that link.
-
A thumbnail is shown for JPEG, PNG, WebP, AVIF, GIF, HEIC and HEIF images. Any other file shows its file extension instead.
-
When the folder above is public too, the page links up to that folder's gallery.
-
A public folder with nothing public in it says "Nothing is shared here yet."
-
The page never shows files that are not public, and never shows descriptions, tags, statuses, members or anything else about the workspace.
-
The page needs no sign-in and no cookie, runs no scripts and asks search engines not to index it.
-
The page is kept by browsers and caches for up to 60 seconds. A rename or a new file inside can take a minute to show.
-
A gallery that does not work answers
404 NOT_FOUND, the same answer as an unknown file link: a restricted folder, a trashed folder, a folder of a deleted workspace and an address that never existed look alike.
Moves and restores that change access
Moving a file into a public folder can make it public. Moving it out can stop its link. The same goes for moving a folder with everything in it, and for restoring from the trash. Two rules protect against surprises:
- A change of who can open files asks first. A move that would make
files public, or stop public links, is refused with
409 CONFLICT, reasonVISIBILITY_CHANGE, and changes nothing. The same request withconfirmVisibilityChange: truegoes ahead. - Only owners and admins make files public this way. A member's move that would make files public is refused outright, confirmed or not.
Moves
- A move changes access when the set of public files is different after it. A file with an allowing status moved into a public folder becomes public. A file that was public only through its folder stops being public when it leaves that folder.
- A move changes nothing when the file is restricted before and after, or public before and after. Moving a file between two public folders, or moving a file that is public itself, asks nothing.
- A file without an allowing status never becomes public by a move. Any member can move it into a public folder without a question. It becomes public later only if an owner or admin gives it an allowing status, and that change asks first.
- Moving a folder counts every file in it and below it.
- The refusal says what would happen:
details.becomePublicis the number of files whose link would start,details.stopPublicthe number whose link would stop, anddetails.publicViais the public folder that shares the destination (idandname), ornull. - A refused move changes nothing. The file or folder stays where it was.
- A confirmation is never needed when access does not change. Sending
confirmVisibilityChange: truethen makes no difference.
What each caller gets for a move that changes access:
| Who | Move that only stops public links | Move that makes files public |
|---|---|---|
| Owner or admin, in a browser | 409 VISIBILITY_CHANGE until confirmed, then it moves. | 409 VISIBILITY_CHANGE until confirmed, then it moves. |
| Member, in a browser | 409 VISIBILITY_CHANGE until confirmed, then it moves. | 403 FORBIDDEN, reason MAKES_FILES_PUBLIC, with details.becomePublic. Confirming does not help. |
Credential with files:write only | 409 VISIBILITY_CHANGE until confirmed, then it moves. | 403 FORBIDDEN, reason INSUFFICIENT_SCOPE, with details.requiredScopes ["files:approve"], also for an owner's or admin's credential. |
Credential with files:write and files:approve, member is an owner or admin with a verified email | 409 VISIBILITY_CHANGE until confirmed, then it moves. | 409 VISIBILITY_CHANGE until confirmed, then it moves. |
Credential with files:approve whose member is no longer an owner or admin | 409 VISIBILITY_CHANGE until confirmed, then it moves. | 403 FORBIDDEN, reason MAKES_FILES_PUBLIC. |
Credential with files:approve whose member's email is not verified | 409 VISIBILITY_CHANGE until confirmed, then it moves. | 403 EMAIL_NOT_VERIFIED. |
In the organization folder only owners and admins move anything, so the member rows do not arise there.
The checks for a move happen in this order:
- Not signed in or an invalid credential:
401 UNAUTHENTICATED. - A credential without
files:write:403 FORBIDDEN, reasonINSUFFICIENT_SCOPE. - The workspace or organization is out of reach:
404 NOT_FOUND. - An organization folder file or folder and you are not an owner or admin:
403 FORBIDDEN. - The file or folder is unknown:
404 NOT_FOUND. It is in the trash:409 CONFLICT, reasonIN_TRASH. It changed since you read it:409 STALE_LOCK_VERSION. - The destination is not a live folder of the same workspace or
organization folder:
422 VALIDATION_FAILEDonfolderID(for a file) orparentID(for a folder). A folder moved into itself or below itself:409 CONFLICT, reasonCYCLE. - The move would make files public and the credential lacks
files:approve:403 FORBIDDEN, reasonINSUFFICIENT_SCOPE. - The move would make files public and you are not an owner or admin:
403 FORBIDDEN, reasonMAKES_FILES_PUBLIC. - The move would make files public through a credential whose member's
email is not verified:
403 EMAIL_NOT_VERIFIED. - The move would start or stop public links and
confirmVisibilityChangeis nottrue:409 CONFLICT, reasonVISIBILITY_CHANGE. - Otherwise it moves:
200.
The other rules of moving are in Folders, moving and finding.
Moving to the trash
- Moving a public file to the trash is allowed and asks nothing. Its link stops at once.
- Moving a folder to the trash stops the link of every public file inside.
The answer counts them in
publicLinkCount. - The trash remembers, for each file, whether it was public at that moment.
Restores
- A restore puts files back as they were. A file that was public when it
went to the trash comes back public, at the same link, for whoever may
restore it: a member, or a credential with
files:write, too. No confirmation is asked. - This holds for a file that was public itself, and for a file that was public through a folder that went to the trash together with it.
- A restore that would make a file public that was not public when it was
trashed follows the rule for making files public. This happens when the
file's folder was moved under a public folder while the file was in the
trash, or when the folder was shared meanwhile.
- An owner or admin restores it. No confirmation is asked, and the file comes back public.
- A member is refused with
403 FORBIDDEN, reasonMAKES_FILES_PUBLIC.details.becomePubliccounts only the files that would be newly public. - A credential without
files:approveis refused with403 FORBIDDEN, reasonINSUFFICIENT_SCOPE. - A refused restore restores nothing. When a folder is restored with many files and one of them would be newly public, the whole folder stays in the trash.
- A file that was public when trashed and can no longer be public comes back restricted, without a refusal. For example its status stopped allowing public use meanwhile, or the folder that shared it was restricted.
- A file restored on its own returns to its folder if that folder is live, otherwise to the top level. At the top level no folder shares it.
- Signed links made before the trash do not come back. The public link does.
- Who may restore at all, and what else a restore does, is described in Trash and restore.
Suggestions
Applying a suggestion that moves files follows the same rule: a member's
apply that would make files public is refused with MAKES_FILES_PUBLIC. See
The organization folder and
suggestions.
Location data
- A photo can carry the place it was taken, as a GPS position in its metadata.
- A public link serves the original exactly as it was uploaded, with its metadata. Anyone with the link can read that position.
- Talewright records, for each version, whether its original holds a GPS
position. The API gives it as
hasLocationDataon the version. - It is read from the EXIF metadata of JPEG, PNG, WebP, AVIF, HEIC and
HEIF images, and it is
trueonly when both a latitude and a longitude are present. - It is
falsefor every other file type, and for versions uploaded before this was recorded. - While a file's status allows public use and its current version holds location data, the sharing controls say: "The original contains location data that anyone with the link can read."
- The warning is shown to everyone who sees the sharing controls, members included. It is shown whether or not the file is public yet. It is not shown while the file's status does not allow public use, since the file cannot be public then.
- The warning follows the current version. Replacing the photo with a version without a position removes it.
- It is a warning only. It does not stop anyone from making the file public, and nothing is removed from the original.
- Resized image variants carry no metadata, so they carry no position. See Image variants.
Copy link
- The sharing controls have two copy buttons, each named for what it copies.
- "Copy public link" is there only while the item is public. It sits in the box named "Public link", which shows the link, and copies it: a file's public link, or a folder's gallery address.
- "Copy link for members" is always there. It copies the address of the
item's page in the app, such as
https://app.usetalewright.com/w/{workspaceID}/files/{fileID}. That address works only for people who can sign in and open the workspace. It is the same address whether or not the item is public. - "Copy link" in a row's menu copies the app address of a file. For a public folder it copies the gallery address; for a restricted folder, the app address.
- Everyone who can open the item can copy its links, members included.
- A public link is the same for everyone. Copying it creates nothing and is not recorded.
In the app
Where sharing is
- A file's page. "Details", under the preview, has the section "Sharing" in its right column. On a narrow screen it is further down the same page, under the section "Details".
- An open folder. The details beside the listing have the card "Sharing" for the folder. On a narrow screen the toolbar's "Details" button opens them.
- A row's menu. Each file and folder row has a menu, from the button "File actions for {name}" or "Folder actions for {name}", or a right-click. It has "Share", which opens the dialog "Share {name}", and for owners and admins "Make public" or "Make restricted".
- The command palette. "Share" opens the same dialog for the selected or open item. "Change general access" switches the item's setting.
- A file in the trash has no "Sharing" section.
The section, the card and the dialog hold the same controls.
The General access control
For an owner or admin, on an item that can be shared:
- "General access" is a picker with "Restricted" and "Anyone with the link".
- Choosing "Anyone with the link" makes the item public. The box "Public link" appears with the link and "Copy public link".
- Choosing "Restricted" restricts it. The box goes away.
One line with an icon says who can open the item now. It is below the picker, or first in the controls when there is no picker:
- "Only people with access to this workspace can open it."
- In the organization folder: "Only people in the organization can open it."
- For a public file: "Anyone on the internet with the link can open it."
- For a public folder: "Anyone on the internet with the link can open it and the files in it whose status allows public use."
- When a folder above shares it: "Anyone on the internet with the link can open it, because {folder} is shared. Restrict {folder} to stop that." The first {folder} is a link that opens that folder, where its sharing can be changed. Following it from the "Share" dialog closes the dialog. The picker still reads the item's own setting, "Restricted".
- On a folder whose own setting is "Restricted" and that a folder above shares, the picker is disabled and that line is its explanation: the folder's own setting changes nothing while the folder above is shared. Restrict the folder above, or move this folder out, and the picker works again. "Make public" in the row menu and "Change general access" in the command palette are still offered and change only the folder's own setting.
- On a file that a folder above shares, the picker stays enabled. Choosing "Anyone with the link" there changes the file's own setting only. It counts once the folder above is restricted or the file is moved out.
The line says what is true now, not the item's own setting. The sharing controls show no badge.
A file whose status does not allow public use has no picker. A second line says why it cannot be public:
- "Cannot be public: status is "{status}"."
- "Cannot be public: it has no status."
Owners and admins get "Set status" at the end of that line:
- On a file's page it opens the picker of the "Status" section above.
- In the "Share" dialog it opens the dialog "Status of {name}", which takes the place of the "Share" dialog.
If an item's own setting is "Anyone with the link" while it is not public, the second line is a warning instead, in the warning color with an icon: "Not public yet: status is "{status}".", "Not public yet: it has no status." or "Not public: it is in the trash." Owners and admins then see the picker disabled. The app does not normally reach this state: a blocking status sets a file's own setting back to "Restricted", and items in the trash show no sharing controls.
A file whose original holds location data, and whose status allows public use, adds a warning line with an icon: "The original contains location data that anyone with the link can read."
Messages when a change fails:
- "This file needs a status that allows public use. Set one, then share it." - the status changed since the page loaded.
- "Only owners and admins change who can open it."
- "Could not change access. Try again."
Copying says "Copied the link". If the browser refuses, "Copy public link" says "Could not copy. Select the link and copy it." and "Copy link for members" says "Could not copy the link."
The Share dialog
- Choose "Share" in the row menu of a file or folder.
- The dialog "Share {name}" shows the controls above.
- "Done" closes it. Changes are saved the moment you choose them; there is nothing to save on closing.
The dialog always loads the item as it is now, so it shows a change made in another tab or by someone else.
Make public and Make restricted
- Owners and admins see "Make public" in the row menu of an item whose own setting is "Restricted", and "Make restricted" on one whose own setting is "Anyone with the link".
- A file is offered "Make public" only while its status allows public use.
- The app confirms with "Anyone with the link can open {name}" or "{name} is restricted".
- If the change fails, the app shows the same messages as the "General access" control, for example when the file's status changed since the list loaded.
- "Make restricted" changes the item's own setting. A file that a folder above shares stays public through that folder.
Sharing a folder
- A folder's "Share", its "Sharing" card and "Make public" work as for a file. No status is involved.
- While the folder is public, "Public link" holds the gallery address.
- A folder inside a public folder is public through it, whatever its own setting. Its "General access" picker is disabled while its own setting is "Restricted", and the line under it links to the folder above. See The General access control.
- "Make public" in the row menu of such a folder changes its own setting only. Nothing else changes while the folder above is shared.
- The folder's "Statuses" card has "Set status" for owners and admins. It sets one status on every file in the folder and below it. See Setting a status on files.
Badges in the listing
- A file or folder that anyone with the link can open now shows a badge: "Public" when it is shared itself, "Public via folder" when a folder above shares it. Hovering says "Anyone with the link" or "Anyone with the link, through {folder}".
- An item that is not public now shows no badge, whatever its own setting.
- The card "Folder details" shows who opens the open folder: "Restricted", "Every workspace", "Public" or "Public, from {folder}".
Moving in the app
- The app moves at once whatever does not change access.
- For the rest it asks once, for the whole move: "Change who can open these files?" with lines such as "3 files will become public via Press kit." and "2 public links will stop working.", and the buttons "Cancel" and "Move".
- "Cancel" leaves those items where they were. The items that did not need the question have already moved.
- After a move the app shows "Moved {name} to {folder}" with "Undo" for 8 seconds. "Undo" moves the items back and with them the access they had, without asking again. It answers "Moved {name} back".
- A member whose move would make files public is told, without a question: "That would make 1 file public. Only an owner or admin can make files public." The file stays where it was.
- A member whose "Undo" would make files public again gets the same message. See the edge cases.
Trash and restore in the app
- Moving public files to the trash, or a folder holding them, says how many links stopped, for example "1 public link stopped working until restored.", with "Undo".
- "Undo" restores the items and answers "Restored {name}".
- "Restore" in the trash, and on a trashed file's page, brings a file back with the link it had.
- A member whose restore would make a file public that was not public when trashed reads "That would make 1 file public. Only an owner or admin can make files public." The file stays in the trash.
What members see
A member sees the same "Sharing" section or card and "Share" dialog, read-only:
- The line that says who can open the item now.
- No "General access" picker, whatever the item's own setting.
- While the item is public: the "Public link" box with "Copy public link".
- Always: "Copy link for members" for the app address.
- The reason a file cannot be public, without "Set status", and the location data warning, as owners and admins see them.
- No "Make public", "Make restricted" or "Set status" in menus.
For agents
A credential reads who can open a file. It cannot change general access.
What it can do that touches public links: move, trash and restore files
and folders, and set statuses if it holds files:approve.
| Operation | Capability ID | MCP tool | Scope |
|---|---|---|---|
GET /v1/workspaces/{workspaceID}/files/{fileID} | workspace.files.get | workspace_files_get | files:read |
GET /v1/workspaces/{workspaceID}/files | workspace.files.search | workspace_files_search | files:read |
GET /v1/workspaces/{workspaceID}/folders | workspace.folders.list | workspace_folders_list | files:read |
PATCH /v1/workspaces/{workspaceID}/files/{fileID} | workspace.files.update | workspace_files_update | files:write; files:approve too when it makes the file public |
PATCH /v1/workspaces/{workspaceID}/folders/{folderID} | workspace.folders.update | workspace_folders_update | files:write; files:approve too when it makes files public |
DELETE /v1/workspaces/{workspaceID}/folders/{folderID} | workspace.folders.trash | workspace_folders_trash | files:write |
POST /v1/workspaces/{workspaceID}/files/{fileID}/restore | workspace.files.restore | workspace_files_restore | files:write; files:approve too when it makes a file newly public |
POST /v1/workspaces/{workspaceID}/folders/{folderID}/restore | workspace.folders.restore | workspace_folders_restore | files:write; files:approve too when it makes files newly public |
PUT /v1/workspaces/{workspaceID}/files/{fileID}/visibility | workspace.files.visibility.set | none | session only |
PUT /v1/workspaces/{workspaceID}/folders/{folderID}/visibility | workspace.folders.visibility.set | none | session only |
Every operation has a twin for the organization folder (the API's library)
under /v1/organizations/{organizationID}/library, with a capability ID that
starts with library. and a tool that starts with library_.
What a file and a folder say about access
| Property | On | Meaning |
|---|---|---|
visibility | file, folder | The item's own setting: restricted or public. |
public | file | true while anyone with the link opens the file now. A trashed file keeps its visibility but reads false. |
publicURL | file (when read on its own), folder | The public link, or the folder's gallery address, while it works. Otherwise null. Files in a list do not carry it; read the file. |
publicVia | file, folder | {id, name} of the nearest public folder that shares it, or null. |
status.allowsPublic | file | Whether the file's status lets it be public. status is null for a file without one. |
currentVersion.hasLocationData | file | Whether the current original holds a GPS position. |
To tell whether a file is public, read public. Do not derive it from
visibility.
Reading a file's access
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/files/$FILE_ID" \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY"
The parts of the answer that matter here:
{
"id": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
"name": "logo.png",
"status": {
"id": "0192e7c4-0c33-7f72-a043-6ebc9c8f7052",
"name": "Approved for public use",
"allowsPublic": true
},
"visibility": "restricted",
"public": true,
"publicVia": {
"id": "0192f0b2-1111-7aaa-8bbb-000000000010",
"name": "Press kit"
},
"publicURL": "https://files.talewrightusercontent.com/p/3f9c2b7e4a1d4c0e9b8a7f6e5d4c3b2a/logo.png"
}
This file is not shared itself. It is public because the folder "Press kit" is.
Moving a file into a public folder
curl -s -X PATCH "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/files/$FILE_ID" \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expectedLockVersion": 4, "folderID": "0192f0b2-1111-7aaa-8bbb-000000000010"}'
If the file's status allows public use and the credential holds
files:approve for an owner or admin, the first answer is the question:
{
"error": {
"code": "CONFLICT",
"message": "This changes who can open some files; send it again with confirmVisibilityChange to go ahead",
"details": {
"reason": "VISIBILITY_CHANGE",
"becomePublic": 1,
"stopPublic": 0,
"publicVia": {
"id": "0192f0b2-1111-7aaa-8bbb-000000000010",
"name": "Press kit"
}
}
},
"requestID": "01928f3e-7c1a-7d2b-9a41-3f0c2d9e8b17"
}
- Nothing has moved.
- Show the counts to the person you act for. Repeat the request with
"confirmVisibilityChange": trueonly when they agree. - The repeated request answers
200with the file, now withpublictrueandpublicVianaming the folder. - A credential without
files:approvegets403 FORBIDDENwithdetails.reasonINSUFFICIENT_SCOPEinstead. Do not retry; a person with the right role moves the file. - A credential whose member is not an owner or admin gets
403 FORBIDDENwithdetails.reasonMAKES_FILES_PUBLICanddetails.becomePublic.
What the session-only operations take and return
| Operation | Body | Success |
|---|---|---|
| Set a file's general access | {"visibility": "public"} or {"visibility": "restricted"} | 200 with the file |
| Set a folder's general access | The same | 200 with the folder |
An agent that needs a file made public asks a person. It can prepare the
ground: an agent with files:approve sets a status that allows public
use, and an owner or admin then shares the file in the app.
Edge cases
| Situation | What happens | Why |
|---|---|---|
| An owner makes public a file with the default status | 409 CONFLICT, reason STATUS_BLOCKS_PUBLIC. The file stays restricted. | The default status never allows public use. |
| An owner makes public a file without a status | 409 CONFLICT, reason STATUS_BLOCKS_PUBLIC, saying the file has no status. | A file without a status is never public. |
| A member makes public a file whose status allows public use | 403 FORBIDDEN. | Only owners and admins change general access. |
| A member of the workspace who is admin of that workspace shares a file in it | It works. | The effective workspace role counts for workspace files. |
| That workspace admin shares an organization folder file | 403 FORBIDDEN. | The organization role counts in the organization folder. |
| An API key with every scope, of an owner, sets general access | 403 FORBIDDEN, reason SESSION_REQUIRED. Nothing changes. | General access needs a person in a browser. |
| An MCP client calls a tool to set general access | There is no such tool. | The operation is not offered over MCP. |
| A file is made public twice in a row | The second request answers 200 and changes nothing. | It already has that setting. |
| A public file is restricted and made public again | It has the same link as before. | A file's link never changes. |
| A public file is renamed | The old link and the new one both open it. | The file is found by the 32 digits, not the name. |
| Someone opens the link with a different name at the end | The file opens. A saved copy gets the file's current name. | The name in the link is for people only. |
| A public file gets a new version | The same link serves the new version at once. | A link follows the current version. |
| A member uploads a new version of a public file | The link serves the member's version. No approval is asked. | The status and the sharing belong to the file, and members may replace workspace files. |
| A file is uploaded into a public folder | It is not public and not on the gallery page. | It starts with the default status or none. |
| An owner then gives that file an allowing status | The change asks first, then the file is public through the folder. | A status change that makes files public needs a confirmation. See Statuses. |
| A file in a public folder gets a status that does not allow public use | Its link stops and it leaves the gallery page. The folder stays public. | The strict rule holds per file. |
| A file that is public itself sits in a public folder, and the folder is restricted | The file stays public. | Restricting a folder stops only the links the folder gave. |
| A file is public only through its folder, and an owner chooses "Make restricted" on the file | Nothing changes: its own setting was already "Restricted". It stays public through the folder. | The folder shares it. Restrict the folder or move the file out. |
| A subfolder of a public folder is set to "Restricted" | Its files stay public. In the app the subfolder's "General access" picker is then disabled, and the line under it names the folder above as a link. | The folder above shares everything below it. |
| A subfolder whose own setting is "Anyone with the link" sits in a public folder | Its picker works. Once it is set to "Restricted", the picker is disabled while the folder above shares it. "Make public" in its row menu and "Change general access" in the command palette still change its own setting, which enables the picker again and changes nothing else. | Its own setting changes nothing while the folder above shares it. |
| A folder is public and the folder above it is made public too | Everything stays public. The item's publicVia names the nearest public folder. | The nearest public folder at or above counts. |
| A public folder holds only files without an allowing status | The gallery opens and says "Nothing is shared here yet." | The folder is public; none of its files is. |
| A public folder holds 1,500 public files | The gallery lists the first 1,000 by name. All 1,500 links work. | The gallery lists at most 1,000 files. |
| Someone opens the gallery address of a restricted folder | 404 NOT_FOUND, the same as for an unknown file link. | Nobody can tell that the folder exists. |
| A trashed folder's general access is changed | 409 CONFLICT, reason IN_TRASH. | Restore it first. |
| A trashed file's general access is changed | 409 CONFLICT, reason IN_TRASH. | Restore it first. |
| A public file is read while it is in the trash | visibility is public, public is false, publicURL is null. | The setting is kept for a restore; the file is not public. |
| A public file is moved to the trash | It works without a question. The link answers 404 at once. | Trashing is never refused because a file is public. |
| A member restores a file that was public when it went to the trash | It comes back public at the same link. | A restore puts files back as they were. |
| A file with an allowing status, not public, is trashed. Its folder is then moved under a public folder. A member restores the file | 403 FORBIDDEN, reason MAKES_FILES_PUBLIC, becomePublic 1. The file stays in the trash. | The restore would make a file public that was not public before. |
| An admin restores that same file | It is restored and public. No confirmation is asked. | Owners and admins restore without a question. |
| A folder is restored that holds one file that was public when trashed and one that would be newly public, by a member | Refused, becomePublic 1. Both files stay in the trash. | Only the newly public file counts, and a refused restore restores nothing. |
| A public file is trashed, and its status stops allowing public use meanwhile | Anyone who may restore it restores it. It comes back restricted. | It can no longer be public, and nothing becomes public. |
| A file public through its folder is trashed on its own, then the folder is trashed too, then the file is restored | The file returns to the top level and is not public. | Its folder is not live, and no folder shares the top level. |
| A member moves a file without an allowing status into a public folder | It moves without a question and stays restricted. | Nobody's access changes. |
| A member moves a file with an allowing status into a public folder | 403 FORBIDDEN, reason MAKES_FILES_PUBLIC, with or without the confirmation. Nothing moves. | Only owners and admins make files public. |
| A member moves a folder that holds such a file under a public folder | The same refusal, counting the files inside. | A folder move counts every file below it. |
| A member moves a public file out of a public folder | 409 CONFLICT, reason VISIBILITY_CHANGE, stopPublic 1. Confirmed, it moves and the link stops. | Stopping links needs only the confirmation. |
| That member chooses "Undo" | Refused: "That would make 1 file public. Only an owner or admin can make files public." The file stays out. | Moving it back would make it public again, which a member may not do. |
| A member trashes a public file and chooses "Undo" | The file is restored and public again. | It was public when it went to the trash. |
| A file is moved from one public folder to another | It moves without a question. Its link keeps working. | It is public before and after. |
| A file that is public itself is moved into a restricted folder | It moves without a question and stays public. | Its own sharing does not depend on the folder. |
A move is sent with confirmVisibilityChange: true although nothing would change | It moves. | The confirmation only matters when access changes. |
| An owner drags ten files into a public folder, three of which would become public | Seven move at once. The app asks once about the three. | The app asks only for the items that change access. |
An admin's key with files:write moves an approved file into a public folder | 403 FORBIDDEN, reason INSUFFICIENT_SCOPE, requiredScopes ["files:approve"]. | Write scopes never include the authority to make files public. |
A member's key that still holds files:approve after the member was demoted makes the same move | 403 FORBIDDEN, reason MAKES_FILES_PUBLIC. | The member's role is checked on every use. |
| A member applies a suggestion whose move would make a file public | 403 FORBIDDEN, reason MAKES_FILES_PUBLIC. The file does not move. | The same rule as for a move. |
| An owner shares a file at the very moment another owner gives it a blocking status | One of the two is handled first. Either the share is refused with STATUS_BLOCKS_PUBLIC, or the status change restricts the file again. It never ends public with a blocking status. | The two changes are handled one after the other. |
| An owner chooses "Anyone with the link" on a page loaded before the status changed | "This file needs a status that allows public use. Set one, then share it." The file stays restricted. | The rule is checked at the moment of the change. |
| Two owners set different general access on one file at the same moment | Both succeed. The later setting stays. | The requests are handled one after the other. |
| A workspace with public files is deleted and later restored | The links stop at the deletion and work again, at the same addresses, after the restore. | Nothing in a deleted workspace is public, and addresses are kept. See Workspaces. |
| A public file is deleted for good | Its link answers 404 and never works again. | The file no longer exists. |
| A public photo's original holds a GPS position | The sharing controls warn about it. Anyone with the link can read the position from the file. | The link serves the original with its metadata. |
| That photo is replaced by a version without a position | The warning goes away. Earlier versions keep their own hasLocationData. | The warning follows the current version. |
| A video or a raw photo holds a position | No warning is shown. | Positions are read only from the EXIF data of JPEG, PNG, WebP, AVIF, HEIC and HEIF images. |
| Someone outside the organization changes or reads general access through the API | 404 NOT_FOUND, as for an unknown workspace. | Outsiders cannot tell that the workspace or file exists. |
Errors
| Code | Status | When | What to do |
|---|---|---|---|
UNAUTHENTICATED | 401 | Not signed in, or an invalid credential. | Sign in or use a valid credential. |
FORBIDDEN | 403 | A member changes general access. A member changes anything in the organization folder. | Ask an owner or admin. |
FORBIDDEN, reason SESSION_REQUIRED | 403 | A credential sets a file's or folder's general access. | A person does this in a browser. |
FORBIDDEN, reason MAKES_FILES_PUBLIC | 403 | A move, a restore or an applied suggestion would make files public, and the person (or the credential's member) is not an owner or admin. details.becomePublic counts the files. Message: "This would make files public; only an owner or admin can do that". Nothing changed. | Ask an owner or admin to do it. Do not retry. |
FORBIDDEN, reason INSUFFICIENT_SCOPE | 403 | A credential without files:approve makes a move or a restore that would make files public. details.requiredScopes is ["files:approve"]. Nothing changed. | Use a credential that holds files:approve, or ask a person. |
EMAIL_NOT_VERIFIED | 403 | A credential with files:approve would make files public by a move or a restore, and its member's email is not verified. | The member verifies their email address. |
NOT_FOUND | 404 | The workspace, organization, file or folder is unknown, deleted for good or out of your reach. On the files host: the link's file or folder is not public now, or never existed. | Check the ID. For a link: ask the owner whether the file is still shared. |
CONFLICT, reason STATUS_BLOCKS_PUBLIC | 409 | A file is made public while it has no status, or a status that does not allow public use. | An owner or admin sets a status that allows public use first. |
CONFLICT, reason IN_TRASH | 409 | General access of a trashed file or folder is changed, or a trashed item is moved. | Restore it first. |
CONFLICT, reason VISIBILITY_CHANGE | 409 | A move would start or stop public links and was not confirmed. details.becomePublic, details.stopPublic and details.publicVia say what would change. Nothing changed. | Show the counts to a person, then repeat with confirmVisibilityChange: true. |
CONFLICT, reason NOT_IN_TRASH | 409 | A restore of something that is not in the trash, or that went to the trash with its folder. | Restore the folder instead. See Trash and restore. |
STALE_LOCK_VERSION | 409 | A move names an expectedLockVersion that is no longer current. | Read the item again and repeat. |
VALIDATION_FAILED | 422 | visibility is missing or not restricted or public; a move's destination is not a live folder of the same workspace or organization folder. | Correct the field. |
RATE_LIMITED | 429 | A credential passed its request limit. | Wait for Retry-After seconds. |
See Errors for the shape of every error, and Errors on the files host for what a link answers.
Limits
| What | Value |
|---|---|
| General access settings | 2: "Restricted" and "Anyone with the link" |
| Public links per file | 1, for the file's whole life |
| Gallery addresses per folder | 1, for the folder's whole life |
| Random part of a link | 32 hexadecimal digits |
| Expiry of a public link | None |
| Subfolders listed on a gallery page | Up to 1,000 |
| Files listed on a gallery page | Up to 1,000 |
| Time a browser may reuse a public file it has loaded | 60 seconds |
| Time a gallery page may be reused | 60 seconds |
| Time the app offers "Undo" after a move or a trash | 8 seconds |
| Time a trashed file can be restored with its link | 30 days. See Trash and restore |
More in Limits.
Questions and answers
What does "Anyone with the link" mean exactly? Anyone on the internet who has the link opens the file, without an account and without signing in. Nobody needs to be invited.
What does "Restricted" mean? Only people who can open the file's workspace. For an organization folder file: every member of the organization.
Why can't I make this file public? One of three reasons. You are not an owner or admin: then the sharing controls have no "General access" picker. The file has no status, or a status that does not allow public use: the sharing controls say "Cannot be public" and why. Or the file is in the trash.
I set a status that allows public use. Why is the file not public? The status only allows it. An owner or admin still chooses "Anyone with the link" on the file, or the file must be in a public folder.
Can a member share a file? No. Members see who can open a file and can copy its link. Owners and admins change it.
Can an agent or an API key make a file public?
Not directly, whatever its scopes: general access needs a person in a
browser. A credential with files:approve, acting for an owner or admin,
can make a file public indirectly in two ways: by setting an allowing
status on a file that sits in a public folder, or, if it also holds
files:write, by moving a file with an allowing status into a public
folder. Both are refused until repeated with an explicit confirmation.
Does the link change when I rename, replace or re-share the file? No. A file has one link for its whole life.
Can I get a new link for a file, so the old one stops working? No. To retire a link for good, upload the file again as a new file and share that one, then restrict or trash the old file.
Can I link to one specific version? No. The public link always serves the current version.
What do people see when the link no longer works? "Not found", the same as for a link that never existed. They cannot tell whether the file was restricted, trashed or never there.
I restricted a file but my browser still shows it. Why? A browser may reuse a file it already loaded for up to 60 seconds. After that it asks again and gets "not found".
Can I set a password or an expiry date on a public link? No. To end access, restrict the file.
Can I share a file with one outside person only? No. A file is open to people who can open its workspace, or to anyone with the link.
Can search engines find my public files? A link can be found only by someone who has it; it cannot be guessed. If you publish the link on a web page, anyone who reads that page has it. The gallery page of a public folder asks search engines not to index it.
How do I share many files at once? Put them in a folder and make the folder public. Every file in it whose status allows public use is public, and the folder has a gallery page that lists them.
I made a folder public. Why are some of its files missing from the gallery? They have no status, or a status that does not allow public use. Or they are in a subfolder, which has its own gallery page.
Does making a folder public make everything in it public? Only the files whose status allows public use. The rest stay restricted until an owner or admin gives them an allowing status.
I uploaded a file into a public folder. Is it public? No. A new upload is never public. An owner or admin gives it a status that allows public use first.
Can I keep one subfolder of a public folder private? Not by restricting it: the folder above shares everything below. Move the subfolder out, or give its files a status that does not allow public use.
Why is "General access" greyed out on my folder? A folder above it is public and shares it, so the folder's own setting would change nothing. The line under the picker names that folder as a link. Restrict that folder, or move this one out of it.
Why did moving a file ask me "Change who can open these files?" The move would make files public, because the destination is in a public folder, or stop public links, because the files leave one. Nothing moves until you confirm.
Why was my move refused with "Only an owner or admin can make files public"? You are a member, and the move would have made files public. Ask an owner or admin to move them, or move them somewhere that is not shared.
I trashed a public file by mistake. Is the link gone? It stops while the file is in the trash. Restore the file and the same link works again.
Does a public link work while its workspace is deleted? No. It works again, at the same address, after the workspace is restored.
What is the warning about location data? The file is a photo whose metadata holds the GPS position where it was taken. A public link serves the original with that metadata, so anyone with the link can read the position. To avoid that, replace the file with a copy without the position before sharing it.
Does Talewright remove location data from public files? No. The public link serves the original unchanged. Resized image variants carry no metadata.
Can another website show my public images or load a public font? Yes. See Use from other websites.
What do the copy buttons copy? In the sharing controls, "Copy public link" copies the public link and is there only while the item is public. "Copy link for members" copies the address of the item's page in the app, which only people with access can open. "Copy link" in a row's menu copies the app address of a file, or the gallery address of a public folder.
How do I see which files are public?
In the listing, public files and folders carry the badge "Public" or
"Public via folder". Through the API, read public on each file. The
status list counts the public files per status. See
Statuses.
Who made this file public, and when? The audit trail records every change of general access with the person and the time. See Audit trail.
Is an export of the organization affected by sharing? No. An export holds the files, not their sharing settings or public links. See Export.