Statuses
Summary
A status is a label on a file that says what the file may be used for, such as "Approved for public use" or "Internal use only". Every workspace has its own list of statuses, and so does the organization folder. A file carries only a status of its own workspace or organization folder.
A status does more than label. Each status says whether files with it may be public. A file can be opened by anyone with its link only while its status allows public use. A file without a status is never public. Whoever sets statuses therefore decides what can leave the organization.
That is why setting a status is reserved for owners and admins, and why a
credential needs the scope files:approve for it, which no other scope
includes.
This page covers the status lists (the three statuses every new workspace and organization folder starts with, adding, renaming, reordering and deleting), what "allows public use" means, the default status for new uploads, setting a status on one file, a selection or a folder, what a status change does to public links, and filtering by status. The rule for what is public is described in full in Sharing and public links.
Who can do what
"Organization role" is the member's role in the organization. "Effective workspace role" is the stronger of that role (when it is owner or admin) and the member's role in the workspace. See Members and roles.
| Action | Who | Session | Credential (scope) |
|---|---|---|---|
| Read a workspace's status list | Everyone who can read the workspace | Yes | Yes (files:read) |
| Read the organization folder's status list | Every member of the organization | Yes | Yes (files:read) |
| See a file's status | Everyone who can read the file | Yes | Yes (files:read) |
| Filter files by status | Everyone who can read the files | Yes | Yes (files:read) |
| Count the files of one workspace, the organization folder or one folder by status | Everyone who can read the files | Yes | Yes (files:read) |
| Add, rename, reorder or delete a workspace's statuses, change whether one allows public use or is the default | Effective workspace owner or admin | Yes | No |
| Add, rename, reorder or delete the organization folder's statuses, change whether one allows public use or is the default | Organization owner or admin | Yes | No |
| Set or clear the status of files in a workspace | Effective workspace owner or admin | Yes | Yes (files:approve) |
| Set or clear the status of files in the organization folder | Organization owner or admin | Yes | Yes (files:approve) |
- A plain member reads the lists and sees every file's status. A plain member cannot set a status, not even on a file they uploaded.
- A plain member of the organization who is admin or owner of one workspace manages that workspace's status list and sets statuses on its files. They cannot manage the organization folder's list or set statuses on organization folder files: that needs the organization role.
- An owner or admin of the organization manages every workspace's list and the organization folder's.
- A credential sets statuses only with
files:approve.files:writedoes not include it. The credential's member must also be an owner or admin at that moment and have a verified email address. See Credentials and scopes. - A person in a browser session needs no verified email to set a status.
- A status list is managed only by a person in a browser. A credential
that tries gets
403 FORBIDDENwithdetails.reasonSESSION_REQUIRED. - The full matrix is in Roles and permissions.
How it works
The status lists
- Every workspace has exactly one list of statuses, and so does the organization folder. The lists are separate: changing a status of one workspace changes nothing in another workspace or in the organization folder.
- A file only ever has a status of its own workspace or organization folder. Files never move between workspaces or between a workspace and the organization folder, so a file's status always stays in its list.
- The list is ordered. Each status has a
position, counted from 0. - A status has a name, says whether it allows public use (
allowsPublic) and says whether it is the default for new uploads (isDefault). - Everyone who can read a workspace reads its list. Every member of the organization reads the organization folder's list, whatever their role.
- Someone who cannot read the workspace, or who is not a member of the
organization, gets
404 NOT_FOUND, the same answer as for one that does not exist. - A status of one workspace never applies in another workspace, in the
organization folder or in another organization. Naming one on a file is
refused with
422 VALIDATION_FAILED. Managing it through another workspace or the organization folder answers404 NOT_FOUND. - A list can be empty. A workspace or organization folder whose statuses are all deleted has no status to set, and none of its files can be public.
The three starting statuses
Every new workspace and every new organization folder starts with three statuses, in this order:
| Name | Allows public use | Default for new uploads |
|---|---|---|
| Approved for public use | Yes | No |
| Internal use only | No | Yes |
| Not approved | No | No |
- They are ordinary statuses. Whoever manages the list can rename, reorder and delete them like any other.
- Each workspace and the organization folder get their own three, with their own IDs. Changing them in one place leaves the others as they are.
- Nothing ties behavior to their names. What counts is "allows public use" and "default".
Names
- A status name is 1 to 60 characters long.
- Spaces at the start and end are removed before the name is measured and stored.
- A name that is empty after trimming is refused.
- A name with a control character, such as a tab or a line break, is refused, also at the very end of the name.
- A name is unique in its workspace or organization folder, ignoring case. "Licensed" and "licensed" cannot both exist in one list.
- Different workspaces, the organization folder and different organizations can use the same names.
- The name of a deleted status is free at once.
Allows public use
- Each status either allows public use or does not.
- A file is public only while its status allows public use. See the strict rule.
- A status that allows public use does not make anything public by itself. It only makes sharing possible. The file, or a folder above it, must also be shared with "Anyone with the link".
- A status that does not allow public use blocks sharing. Making such a file public is refused, and a link the file had stops.
- A file without a status behaves like a file whose status does not allow public use.
- The app shows "Public use" or "No public use" beside each status.
The default status
- At most one status of each list is the default. New uploads to that workspace or organization folder get it.
- A new file made by an upload starts with the default status. This holds in workspaces and in the organization folder, in the app and through a credential.
- When no status is the default, a new upload starts without a status.
- The default status never allows public use. So a new upload is never public at once, also when it lands in a public folder: someone who may set statuses has to approve it first.
- A change that would leave the default status allowing public use is
refused with
409 CONFLICT, reasonDEFAULT_ALLOWS_PUBLIC, and the message "The status new uploads get cannot allow public use". This covers:- making a status the default while it allows public use,
- allowing public use on the status that is the default,
- doing both in one request.
- One request can stop a status allowing public use and make it the default at the same time. That is accepted.
- Making a status the default takes the mark away from the status that had it. There are never two defaults.
- The default can be switched off without choosing another. Then there is no default.
- A new status is never the default when it is created. It is made the default afterwards.
- The default applies when a file is created. Changing the default later does not change the status of files that exist.
- A replacement upload (a new version of an existing file) keeps the file's status. The default is not applied again.
Adding a status
- Owners and admins of the workspace or organization folder add statuses (see Who can do what).
- A new status needs a name and whether it allows public use.
- It is placed last in the list.
- A workspace or the organization folder has at most 50 statuses. The 51st
is refused with
422 VALIDATION_FAILEDonstatusesand the message "a file space has at most 50 statuses". - The answer is
201with the new status.
The checks happen in this order. The first that fails decides the answer:
- Not signed in:
401 UNAUTHENTICATED. - The workspace or organization is unknown or deleted, or you cannot read
it:
404 NOT_FOUND. - The body is not the expected JSON:
422 VALIDATION_FAILED. - You are not an owner or admin of the workspace or organization folder:
403 FORBIDDEN. - The name breaks the naming rules:
422 VALIDATION_FAILEDonname. - The workspace or organization folder already has 50 statuses:
422 VALIDATION_FAILEDonstatuses. - Another status has the name, ignoring case:
409 CONFLICT, reasonNAME_TAKEN. - Otherwise it is added:
201.
Renaming a status
- Owners and admins of the workspace or organization folder rename a status. The new name follows the naming rules.
- A rename changes the label at once on every file that has the status. A status of the same name in another workspace or the organization folder keeps its name.
- A rename changes nothing else. The status keeps its ID, its files, its place in the list, whether it allows public use and whether it is the default. No public link starts or stops.
- A rename that only changes the case of the name is allowed.
Changing a status
One request can change any of the name, allowsPublic and isDefault.
Properties left out stay as they are.
The checks happen in this order:
- Not signed in:
401 UNAUTHENTICATED. - The workspace or organization is unknown or deleted, or you cannot read
it:
404 NOT_FOUND. - The body is not the expected JSON:
422 VALIDATION_FAILED. - You are not an owner or admin of the workspace or organization folder:
403 FORBIDDEN. - The new name breaks the naming rules:
422 VALIDATION_FAILEDonname. - The status is unknown or belongs to another workspace, the organization
folder or another organization:
404 NOT_FOUND. - The change would leave the default status allowing public use:
409 CONFLICT, reasonDEFAULT_ALLOWS_PUBLIC. - Another status has the new name:
409 CONFLICT, reasonNAME_TAKEN. - The change allows public use, that would make files public, and the
request does not confirm it:
409 CONFLICT, reasonVISIBILITY_CHANGE. - Otherwise it is changed:
200with the status.
A refused request changes nothing, also when only one of several changes in it was the problem.
Reordering
- Owners and admins of the workspace or organization folder put its statuses in a new order.
- The request names every status of that list exactly once, in the new
order. A status left out, named twice, unknown or of another list refuses
the whole request with
422 VALIDATION_FAILEDonstatusIDsand the message "name every status of the file space exactly once". - The order is the order of the list everywhere: in settings, in the status pickers and in the filter.
- Reordering changes no file and no public link.
- The answer is the whole list in its new order.
Deleting a status
- Owners and admins of the workspace or organization folder delete a status. Any status can be deleted, also the default and also one of the three starting statuses.
- Every file that had the status is left without a status. This includes files in the trash.
- Every one of those files becomes restricted. A file that was public, itself or through a public folder, stops being public at once. See what stops a link.
- The files themselves stay. Nothing is trashed or deleted.
- The remaining statuses close the gap: their positions run from 0 again without a hole.
- If the deleted status was the default, there is no default afterwards. New uploads start without a status until another status is made the default.
- The API asks for no confirmation, because deleting a status can only stop public links. It can never make a file public.
- The answer is
200withrestrictedFileCount: the number of files whose public link stopped. Files in the trash are not counted. - Deletion cannot be undone. Adding a status with the same name creates a new status with a new ID. The files do not get it back.
- A file that was public itself does not become public again by getting an allowing status later. It has to be shared again. A file in a public folder becomes public through that folder again when it gets an allowing status, after the confirmation described under Status changes that change access.
- The name is free at once.
The checks happen in this order:
- Not signed in:
401 UNAUTHENTICATED. - The workspace or organization is unknown or deleted, or you cannot read
it:
404 NOT_FOUND. - You are not an owner or admin of the workspace or organization folder:
403 FORBIDDEN. - The status is unknown or belongs to another workspace, the organization
folder or another organization:
404 NOT_FOUND. - Otherwise it is deleted:
200.
A file's status
- A file has one status or none. It never has two.
- The status belongs to the file, not to a version. A new version keeps it.
- Renaming, moving, tagging, describing, trashing and restoring a file do not change its status.
- A file reads its status as
status:{id, name, allowsPublic}, ornullfor "No status". Listings carry it too. - Everyone who can read the file sees its status.
- Search does not look at status names. To find files by status, filter. See Filtering by status.
Setting a status on files
- One request sets one status on 1 to 100 files of one workspace, or of the
organization folder. Sending
statusIDnullclears the status ("No status"). - A file ID named twice counts once.
statusIDmust be present. A request without it is refused and clears nothing: only an explicitnullclears.- The files must be live. If one of them is in the trash, the whole request
is refused with
409 CONFLICT, reasonIN_TRASH, and no file changes. - The files must all belong to the workspace or organization folder in the
path. If one is unknown, in another workspace or deleted for good, the
whole request answers
404 NOT_FOUNDand no file changes. - The status must be one of the list of the workspace or organization folder
in the path. An unknown status, or one of another workspace, the
organization folder or another organization, answers
422 VALIDATION_FAILEDonstatusIDwith the message "Unknown status". - All files change together or none does.
- Setting the status a file already has succeeds and changes nothing else.
- In a workspace the effective workspace role decides: owner or admin. In the organization folder the organization role decides.
- Through a credential the request also needs the scope
files:approveand a verified email address of the credential's member. - Setting a status does not need the file's
lockVersionand does not move it. - The answer is
200with:dryRun:falsefor a change;status: the status set, ornull;fileIDs: the files named, each once;changedFileIDs: those of them that had another status, or none;madePublicFileIDs: the files in a public folder that became public because the status allows public use;restrictedFileIDs: the files whose public link stopped.
Previewing a status change
- The same request with
dryRun: truechanges nothing and answers what it would do right now: the same200answer, withdryRun: true. changedFileIDsnames the files whose status would change,madePublicFileIDsthe files that would become public andrestrictedFileIDsthe files whose public link would stop.- Nothing is set: no status, no public link, no
lockVersionand no entry in the audit trail. - Everything is checked as for the change itself, and refused the same way:
the role, the scope
files:approve, the verified email,statusID,fileIDsand files in the trash. - A preview needs no
confirmVisibilityChangeand never answersVISIBILITY_CHANGE. It is how to learn what a confirmation would allow. - A preview answers for the moment it is asked. If files change before the
change is sent, the change can do something else. It is still refused
with
VISIBILITY_CHANGEwhen it would make files public unconfirmed. - To set a status on more than 100 files, preview every request first, add up the lists, show the totals to a person and only then send the changes. The app does this.
The checks happen in this order. For a credential, see also how a request with a bearer token is checked.
- Not signed in, or an invalid credential:
401 UNAUTHENTICATED. - A credential without
files:approve:403 FORBIDDEN, reasonINSUFFICIENT_SCOPE, withdetails.requiredScopes["files:approve"]. - The workspace or organization is unknown, deleted or out of your reach:
404 NOT_FOUND. - The body is not the expected JSON, for example
statusIDis missing:422 VALIDATION_FAILED. - You are not an owner or admin there:
403 FORBIDDEN. - A credential whose member has no verified email:
403 EMAIL_NOT_VERIFIED. - The status is unknown or not of this workspace or organization folder:
422 VALIDATION_FAILEDonstatusID. fileIDsnames no file or more than 100:422 VALIDATION_FAILEDonfileIDs, with the message "name 1 to 100 files".- A file is unknown or not in this workspace or organization folder:
404 NOT_FOUND. - A file is in the trash:
409 CONFLICT, reasonIN_TRASH. - The status would make files public and the request neither confirms it
nor is a
dryRun:409 CONFLICT, reasonVISIBILITY_CHANGE. - Otherwise the status is set, or with
dryRunonly reported:200.
Status changes that change access
A status change can stop public links, and it can start them. The two are treated differently.
Stopping links needs no confirmation in the API.
- Setting a status that does not allow public use, or clearing the status, makes the files restricted at once. A file that was public itself has its general access set back to restricted. A file that was public through a public folder stops being public too.
restrictedFileIDsin the answer names every file whose link stopped.- Turning "allows public use" off on a status does the same for every file with that status, in its workspace or organization folder, in one step.
- Deleting a status does the same for every file that had it.
- The stopped links answer
404like a link that never existed. Copies a CDN holds are purged. See Caching.
Starting links is refused until confirmed.
- Setting a status that allows public use does not, by itself, make a file public. A file that sits outside any public folder stays restricted until an owner or admin shares it.
- A file inside a public folder is different: with an allowing status it is public through that folder at once. See Public folders.
- So a change that would make files public this way is refused with
409 CONFLICT, reasonVISIBILITY_CHANGE, and changes nothing. This applies to setting an allowing status on files, and to turning "allows public use" on for a status. details.becomePubliccounts the files that would become public.details.stopPublicis0anddetails.publicViaisnullfor a status change.- Repeating the same request with
confirmVisibilityChange: truecarries it out. - A file that becomes public this way for the first time gets its permanent public link at that moment. See The public link.
Going back does not restore a file's own link.
- When a status change stops a file's own link, the file's general access is restricted from then on. Giving the file an allowing status again, or allowing public use on its status again, does not make it public. An owner or admin has to share it again. It then has the same link as before.
- Links that files had through a public folder do come back when their status allows public use again, after the confirmation above, because the folder is still shared.
Counts
- Each status reads
fileCount: the live files of its workspace or organization folder that have it. - Each status reads
publicFileCount: those of them that are public at that moment, themselves or through a folder. These are the links that stop if the status stops allowing public use or is deleted. - The list reads
noStatusFileCount: the live files of the workspace or organization folder without a status. - Files in the trash are not counted.
- The counts cover only the list's own workspace or organization folder, and they are the same for everyone who reads the list, a credential included. These are the counts the confirmations for deleting a status and for stopping public use show.
- Each status also reads
trashedFileCount: the files in the trash of its workspace or organization folder that have it. Deleting the status leaves them without a status too. trashedFileCountis a number only for an owner or admin of the workspace or organization folder signed in to the app, who may delete the status. For everyone else, and for every credential, it isnull.
Counts for one place
The counts above come with the list. A second reading counts one place: one workspace, the organization folder, or one folder of either. The app's "Statuses" card shows it. See The "Statuses" card.
- It answers how many live files of that place have each status, and how many have none.
- Every status of that workspace or organization folder is listed, in the
list's order. A status that no file there has reads
fileCount0. noStatusFileCountis the number of live files there without a status.- Without a folder, every file of the workspace or organization folder is counted, whichever folder it is in.
- With
folderID, the files in that folder and in every folder below it are counted. This differs from a folder's ownfileCount, which counts only the files directly inside it. See Folders, moving and finding. - Files in the trash are not counted. A folder in the trash is not counted with the folder above it.
- A workspace's counts never include organization folder files, and the organization folder's never include a workspace's files.
- Everyone who can read the place reads its counts: the members of a workspace, and every member of the organization for the organization folder.
- The numbers are the same for everyone who can read the place.
- There is no count of public files and no count of trashed files here. The status list of the workspace or organization folder has those, for the whole workspace or organization folder.
- A folder that is not a live folder of that place answers
404 NOT_FOUND: an unknown ID, a folder in the trash, a folder of another workspace, or a folder of the organization folder asked for in a workspace.
Filtering by status
- A file listing takes
status=with a status ID, orstatus=nonefor files without a status. - Any other value answers
422 VALIDATION_FAILEDonstatus. - The ID of a status of another workspace, the organization folder or another
organization is not refused: the listing is empty, since no file there
can carry it. Unlike
field=, which refuses a field of another place with422. - The filter combines with the other filters of a listing. See Folders, moving and finding.
Elsewhere
- The field list of a workspace or the organization folder presents status as its built-in first field. See Fields and tags.
- A suggestion (library proposal) cannot change a status. See Suggestions.
- An organization export lists each workspace's and the organization folder's statuses and each file's status. See Export.
- Every change is recorded in the
audit trail:
file_status.created,file_status.updated,file_status.deletedandfile_status.reorderedfor the list, andfile.status_changedonce per file when a status is set or cleared.
In the app
The status list in settings
Each workspace and the organization folder have their own settings page "Statuses", under "Files & Assets" in its own settings navigation (see Workspaces, The settings navigation). It holds the section "Status":
-
The organization folder's: Settings > File spaces > Organization folder > Statuses. Its address is
https://app.usetalewright.com/settings/organization/{organizationID}/library/statuses. The page is titled "Organization folder". -
A workspace's: Settings > File spaces > {workspace} > Statuses. Its address is
https://app.usetalewright.com/settings/organization/{organizationID}/workspaces/{workspaceID}/files/statuses. The page is titled with the workspace's name. -
The section says "A file can be shared publicly only when its status allows public use."
-
The table "Statuses" shows each status of that workspace or organization folder in order, with the columns:
- "Name": its name, and "New uploads" when it is the default,
- "Sharing": "Public use" or "No public use",
- "Files": the number of files that have it, such as "12 files".
-
Everyone who can open the page sees the list. Owners and admins of that workspace or organization folder (see Who can do what) also get "Add status" and, on each row, a menu "Manage {name}".
-
While the list loads it says "Loading statuses". If it cannot be loaded: "Could not load the statuses."
Adding a status in the app
- Choose "Add status".
- The dialog "Add status" has the field "Name" and the checkbox "Allows public use" with the text "Files with it can be shared publicly."
- "Add status" saves it. The dialog closes and the new status is last in the list.
- A blank or too long name shows "Enter a name of 1 to 60 characters."
- A name another status has shows "Another status has that name."
- With 50 statuses the dialog shows "A workspace or the organization folder can have up to 50 statuses. Delete one to add another."
The "Manage" menu
"Manage {name}" on a status's row offers:
| Item | What it does |
|---|---|
| "Rename" | Opens "Rename {name}" with the field "Name" and the button "Rename". The same two messages as for adding apply. |
| "Allow public use" | Turns "allows public use" on. Asks first when files would become public: see below. |
| "Stop allowing public use" | Shown instead when the status allows public use. Asks first: see below. |
| "Use for new uploads" | Makes the status the default. The mark "New uploads" moves to it. |
| "Stop using for new uploads" | Shown instead on the default status. Afterwards no status is marked. |
| "Move up", "Move down" | Moves the status one place. The first status has no "Move up", the last no "Move down". |
| "Delete" | Asks first: see below. |
- On the default status, the item reads "Allow public use (not while used for new uploads)" and is disabled.
- On a status that allows public use, the item reads "Use for new uploads (not while it allows public use)" and is disabled.
- If the page was loaded before someone else changed the list and the refusal still happens, the row shows "The status new uploads get cannot allow public use. The list is up to date now."
- Any other failure shows the reason, or "Could not change the status. Try again."
Stopping public use. "Stop allowing public use" asks "Stop public use of {name}?".
- With public files it says, for example, "3 public links will stop working. Allowing public use again brings back only the links of files in public folders."
- The count holds both kinds of links: those of files shared on their own, which stay stopped until each file is shared again, and those of files in public folders, which return when public use is allowed again and confirmed.
- Without any it says "No file with it is public. Its files can no longer be shared publicly."
- The buttons are "Cancel" and "Stop public use".
Allowing public use. "Allow public use" takes effect at once when it makes no file public. When files with the status sit in public folders, the app asks "Change who can open these files?" and says, for example, "2 files will become public." The buttons are "Cancel" and "Allow public use".
Deleting. "Delete" asks "Delete {name}?".
- With no files it says "No file has this status."
- With files it says, for example, "4 files will have no status." and, when some are public, "1 public link will stop working."
- Files in the trash of the workspace or organization folder that have the status are named too: "4 files will have no status, and so will 2 files in the trash." When only such files have it: "2 files in the trash will have no status."
- The buttons are "Cancel" and "Delete status".
- Afterwards the app shows "{name} deleted" and, when links stopped, "1 public link stopped working."
A file's status in the app
- In the list view, each file shows its status in the column "Status". When the list is too narrow for the column, the status is under the file's name.
- In the grid view, each tile shows the status under the file's name, as a colored dot and the status name before the size: "Approved for public use ยท 2.4 MB". The dot is green for a status that allows public use and amber for one that does not.
- A file without a status shows no status in the listing: no badge in the list, and only the size on a tile.
- On a file's page, "Status" is the first section in the right column of
"Details", under the preview. On a narrow screen it follows the section
"Details":
- Owners and admins get the picker "Status". It lists "No status" and then every status in order. Choosing one saves it, after the confirmation when it changes who can open the file.
- Everyone else reads the status as a badge, or the badge "No status", and "Owners and admins set the status."
- Under it the section says what the status means for sharing: "Allows public use: this file can have a public link.", "Does not allow public use: this file cannot be public." or "A file without a status cannot be public."
- The page of a file in the trash has no "Status" section.
Setting a status in the app
Only owners and admins are offered these. Each ends with the message "Status set to {name}" for one file or "Set {n} files to {name}" for several. When public links stopped, the message adds, for example, "2 public links stopped working."
One file.
- On the file's page, choose from the picker in the section "Status". While the status keeps the file from being public, "Set status" in the section "Sharing" opens that picker.
- In a listing, open the file's row menu ("File actions for {name}" or a right-click) and choose "Set status". The dialog "Status of {name}" shows the picker "Status" at the file's current status. Choosing a status saves it and closes the dialog.
- A choice that would make the file public or stop its public link asks first. See The confirmation.
- The command palette offers "Set status" under "Files & Assets" when it has exactly one file or folder to act on.
A selection.
- Select files in a listing. Shift-click selects a range. When every loaded row is selected, "Select everything here" selects the rest too, up to 1,000 more files each time it is chosen.
- In the toolbar "Selected files", choose "Set status". It lists "No status" and every status.
- Choosing one sets it on every selected file, after the confirmation when it changes who can open some of them.
- Folders in the selection are left alone. "Set status" is offered when at least one file is selected.
- A selection of more than 100 files is sent in batches of 100. One message reports the whole selection.
- The app first reads what the change would do to every selected file, without changing anything. Only then does it set the status.
- The question about access is asked once, for the whole selection, with the totals. See The confirmation.
A folder.
- Choose "Set status" in the folder's row menu, or at the bottom of the card "Statuses" in the folder's "Details".
- The dialog "Status of {folder}" has the picker "Status".
- After a choice it asks, for example,
Set "Not approved" on 14 files in Press?and adds what the change does to access over all those files: "2 public links will stop working." or "3 files will become public." - "Set status" applies it. "Cancel" leaves everything as it is. The dialog is the confirmation: no second question follows.
- The status is set once, on every live file in the folder and in every folder below it. It is not a property of the folder.
- Files added to the folder later keep their own status.
- An empty folder says "{folder} holds no files." and "Set status" stays disabled.
- If the files cannot be counted: "Could not count the files. Try again."
The confirmation
- Before setting a status, from the picker, a selection or a file's row menu, the app reads the whole effect of the change.
- When no file would become public and no public link would stop, the status is set at once.
- Otherwise the app asks "Change who can open these files?" and says, for example, "101 files will become public." or "2 public links will stop working.", or both. The numbers count every file of the change, however many batches it takes.
- "Set status" then sets the status on all the files. "Cancel" changes nothing: no file gets the status.
- A change that was to make no file public never makes one public. If a file would by the time the status is set, because it was moved into a public folder meanwhile, the change stops with "A file would now become public, which it would not when you chose. Try again." Files of batches already sent keep the new status.
When it fails.
| Message | When |
|---|---|
| "A selected file is in the trash. Clear the selection and try again." | One of the files went to the trash meanwhile. |
| "A file would now become public, which it would not when you chose. Try again." | No file was to become public when the app read the effect, and one would by the time the status is set. |
| "Only owners and admins set statuses." | Your role changed since the page loaded. |
| "A selected file no longer exists. The list is up to date now." | One of the files was deleted for good or moved out of reach. |
| "That status no longer exists. Choose another." | The status was deleted since the page loaded. |
| "Could not set the status. Try again." | Anything else. |
The Status filter
In a listing, "Filter" has the group "Status":
- "All statuses" (no filter), "No status", then every status in order.
- With a status chosen, the listing shows the matching files from every folder of the open workspace or organization folder, not only the open folder.
- "Clear filters" at the bottom of the menu removes every filter.
- The chosen status is part of the page address, so a filtered listing can be bookmarked and shared with a colleague.
The "Statuses" card
The "Details" of a listing hold the card "Statuses". It counts the place you are looking at and names that place in its top right corner.
| Where you are | The card names | The card counts |
|---|---|---|
| Inside a folder of a workspace | The folder | The files in that folder and in every folder below it |
| The top level of a workspace | The workspace | Every file of the workspace, whichever folder it is in |
| Inside a folder of the organization folder | The folder | The files in that folder and in every folder below it |
| The top level of the organization folder | "Organization folder" | Every file of the organization folder |
- It shows how those files split over the statuses of the workspace or organization folder: a bar and one row per status with its number of files, such as "12 files".
- Only statuses that have at least one file there are listed. "No status" is added when some files there have none.
- The numbers are the counts of one place. See Counts for one place.
- A workspace's card never counts organization folder files, and the organization folder's card never counts a workspace's files. No card adds up the organization.
- Files in the trash are not counted.
- The numbers are the same for everyone who can open the place.
- A search or a filter does not change the card. It still counts the open folder, or the whole workspace or organization folder at the top level.
- Opening another folder changes the name at once. The numbers of the place you came from stay, dimmed, until the new ones arrive.
- A folder name too long for the corner is cut short. Pointing at it shows the full name.
- With no files in the place it says "No files yet".
- If it cannot be loaded it says "Could not load statuses." with "Retry".
- Inside a folder, owners and admins find "Set status" at the bottom of the card. It sets one status on every file in the folder and below it. See Setting a status in the app. At the top level of a workspace or the organization folder the card has no "Set status".
- The card updates without a reload after an upload, a status change, a move, a move to the trash and a restore.
- The status list in settings counts the whole workspace or organization folder, whichever folder is open. See Counts.
For agents
A credential reads the status list of a workspace or the organization folder
(the API's library) with files:read and sets statuses on files with
files:approve. Managing a list itself needs a person in a browser.
| Operation | Capability ID | MCP tool | Scope |
|---|---|---|---|
GET /v1/workspaces/{workspaceID}/file-statuses | workspace.file_statuses.list | workspace_file_statuses_list | files:read |
GET /v1/organizations/{organizationID}/library/file-statuses | library.file_statuses.list | library_file_statuses_list | files:read |
GET /v1/workspaces/{workspaceID}/files/status-counts | workspace.files.status.count | workspace_files_status_count | files:read |
GET /v1/organizations/{organizationID}/library/files/status-counts | library.files.status.count | library_files_status_count | files:read |
POST /v1/workspaces/{workspaceID}/files/status | workspace.files.status.set | workspace_files_status_set | files:approve |
POST /v1/organizations/{organizationID}/library/files/status | library.files.status.set | library_files_status_set | files:approve |
POST /v1/workspaces/{workspaceID}/file-statuses | workspace.file_statuses.create | none | session only |
PATCH /v1/workspaces/{workspaceID}/file-statuses/{statusID} | workspace.file_statuses.update | none | session only |
PUT /v1/workspaces/{workspaceID}/file-statuses/order | workspace.file_statuses.reorder | none | session only |
DELETE /v1/workspaces/{workspaceID}/file-statuses/{statusID} | workspace.file_statuses.delete | none | session only |
POST /v1/organizations/{organizationID}/library/file-statuses | library.file_statuses.create | none | session only |
PATCH /v1/organizations/{organizationID}/library/file-statuses/{statusID} | library.file_statuses.update | none | session only |
PUT /v1/organizations/{organizationID}/library/file-statuses/order | library.file_statuses.reorder | none | session only |
DELETE /v1/organizations/{organizationID}/library/file-statuses/{statusID} | library.file_statuses.delete | none | session only |
files:approvedoes not include reading. A credential that should look up statuses and files and then set statuses needsfiles:read(orfiles:write) as well asfiles:approve.GET .../files?status={statusID}andGET .../files?status=nonefilter a listing (workspace.files.search,library.files.search).
Reading the list
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/file-statuses" \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY"
The organization folder's list is at
/v1/organizations/$ORGANIZATION_ID/library/file-statuses. Over MCP the
tools are workspace_file_statuses_list (argument workspaceID) and
library_file_statuses_list (argument organizationID).
{
"items": [
{
"id": "0192e7c4-0c33-7f72-a043-6ebc9c8f7051",
"name": "Approved for public use",
"allowsPublic": true,
"isDefault": false,
"position": 0,
"fileCount": 12,
"publicFileCount": 4,
"trashedFileCount": null,
"createdAt": "2026-11-02T09:14:07Z",
"updatedAt": "2026-11-02T09:14:07Z"
},
{
"id": "0192e7c4-0c33-7f72-a043-6ebc9c8f7052",
"name": "Internal use only",
"allowsPublic": false,
"isDefault": true,
"position": 1,
"fileCount": 87,
"publicFileCount": 0,
"trashedFileCount": null,
"createdAt": "2026-11-02T09:14:07Z",
"updatedAt": "2026-11-02T09:14:07Z"
},
{
"id": "0192e7c4-0c33-7f72-a043-6ebc9c8f7053",
"name": "Not approved",
"allowsPublic": false,
"isDefault": false,
"position": 2,
"fileCount": 5,
"publicFileCount": 0,
"trashedFileCount": null,
"createdAt": "2026-11-02T09:14:07Z",
"updatedAt": "2026-11-02T09:14:07Z"
}
],
"noStatusFileCount": 3
}
- The list is not paged. It holds at most 50 statuses.
- Read it before setting a status: it gives the IDs to send. Read the list of the same workspace or organization folder as the files: a status of another one is refused.
Counting one place
workspace_files_status_count and library_files_status_count count the
live files of one workspace or of the organization folder by status.
folderID is optional and narrows the count to that folder and every folder
below it.
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/files/status-counts?folderID=$FOLDER_ID" \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY"
{
"items": [
{ "id": "0192e7c4-0c33-7f72-a043-6ebc9c8f7051", "name": "Approved for public use", "fileCount": 7 },
{ "id": "0192e7c4-0c33-7f72-a043-6ebc9c8f7052", "name": "Internal use only", "fileCount": 21 },
{ "id": "0192e7c4-0c33-7f72-a043-6ebc9c8f7053", "name": "Not approved", "fileCount": 0 }
],
"noStatusFileCount": 2
}
itemsholds every status of that workspace or organization folder in list order, each withid,nameandfileCount.- The answer is not paged.
- Over MCP the arguments are
workspaceID(ororganizationIDfor the organization folder) and the optionalfolderID. - To list the files behind a number, use the file listing with
status=andunder={folderID}. See Folders, moving and finding.
Setting a status
curl -s -X POST "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/files/status" \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fileIDs": ["0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01"],
"statusID": "0192e7c4-0c33-7f72-a043-6ebc9c8f7052"
}'
{
"dryRun": false,
"status": {
"id": "0192e7c4-0c33-7f72-a043-6ebc9c8f7052",
"name": "Internal use only",
"allowsPublic": false
},
"fileIDs": ["0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01"],
"changedFileIDs": ["0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01"],
"madePublicFileIDs": [],
"restrictedFileIDs": ["0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01"]
}
| Property | Value |
|---|---|
fileIDs (required) | 1 to 100 live files of the workspace, or of the organization folder for the organization folder operation. |
statusID (required) | A status of the same workspace or organization folder, or null to clear the status. |
confirmVisibilityChange | true to go ahead although files in public folders become public. |
dryRun | true to change nothing and answer what the request would do. |
- In the example the file was public, and "Internal use only" does not allow
public use, so its link stopped and it is named in
restrictedFileIDs. - With
"dryRun": truethe same request answers the same lists with"dryRun": true, and the file keeps its status and its link. See Previewing a status change. - For more than 100 files, send several requests. Each request is all or
nothing; the requests are independent of each other. To know the effect
of all of them before any is made, send each with
dryRunfirst and add up the lists. - The same call over MCP is
workspace_files_status_setorlibrary_files_status_set, withworkspaceIDororganizationIDadded to the arguments. See MCP.
When files would become public
Setting "Approved for public use" on a file that sits in a public folder is refused first:
{
"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": null
}
},
"requestID": "01928f3e-7c1a-7d2b-9a41-3f0c2d9e8b17"
}
- Nothing changed. The file keeps its old status and has no public link.
- A request with
"dryRun": trueis not refused. It answers200and names the file inmadePublicFileIDs, so you can ask before you try. - Show the count to the person you act for. Repeat the request with
"confirmVisibilityChange": trueonly when making those files public is what they want. - After the confirmed request the file reads
public: truewith itspublicURL.
What the session-only operations take and return
| Operation | Body | Success |
|---|---|---|
| Add | {"name": "...", "allowsPublic": true | false}, both required | 201 with the status |
| Change | Any of name, allowsPublic, isDefault, confirmVisibilityChange | 200 with the status |
| Reorder | {"statusIDs": ["...", "..."]}, every status once | 200 with the list and noStatusFileCount |
| Delete | none | 200 with {"restrictedFileCount": n} |
Edge cases
| Situation | What happens | Why |
|---|---|---|
| A status named "Licensed" exists and someone adds "licensed" to the same list | 409 CONFLICT, reason NAME_TAKEN. | Names are unique in a workspace or the organization folder, ignoring case. |
| A workspace has "Licensed" and someone adds "Licensed" to another workspace or the organization folder | It works. | Each list is separate. |
| A status is renamed to its own name in another case | It works. | It conflicts with no other status. |
| The name is blank, 61 characters long or ends in a line break | 422 VALIDATION_FAILED on name. | The naming rules. |
| A workspace or the organization folder with 50 statuses adds one more | 422 VALIDATION_FAILED on statuses: "a file space has at most 50 statuses". In the app the dialog shows "A workspace or the organization folder can have up to 50 statuses. Delete one to add another." | The list is full, whatever the name. Delete a status first. |
| A plain member adds, renames, reorders or deletes a status | 403 FORBIDDEN. Nothing changes. | Only the owners and admins of the workspace or organization folder manage its list. |
| A plain organization member who is admin of one workspace manages that workspace's statuses | It works. | The effective workspace role counts for a workspace's list. |
| That member manages the organization folder's statuses | 403 FORBIDDEN. | The organization folder's list needs the organization role owner or admin. |
| An organization owner or admin manages the statuses of a workspace they are not a member of | It works. | Organization owners and admins are owners and admins of every workspace. |
| A status of workspace A is renamed, changed or deleted through workspace B or the organization folder | 404 NOT_FOUND. Nothing changes. | A status is managed only through its own workspace or organization folder. |
| Someone outside the workspace or organization reads its status list | 404 NOT_FOUND, as for an unknown workspace or organization. | Outsiders cannot tell it exists. |
| A credential adds, changes, reorders or deletes a status | 403 FORBIDDEN, reason SESSION_REQUIRED. | A list is managed by a person in a browser. |
| The default status is asked to allow public use | 409 CONFLICT, reason DEFAULT_ALLOWS_PUBLIC. | The default never allows public use, so no upload starts public. |
| A status that allows public use is made the default | 409 CONFLICT, reason DEFAULT_ALLOWS_PUBLIC. | Same rule. |
One request sets isDefault: true and allowsPublic: false on a status that allows public use | It works. The status stops allowing public use, its public files become restricted, and it becomes the default. | The result does not break the rule. |
| A second status is made the default | The first loses the mark. | At most one default. |
| The default is switched off | No status is the default. New uploads start without a status. | A default is optional. |
| The default status is deleted | The same: no default afterwards. Its files are left without a status. | Deleting does not pick a new default. |
| Every status is deleted | The list is empty. No file has a status, none can be public, and uploads start without one. | Public use needs an allowing status. |
| The default is changed | Files that exist keep their status. Only uploads from then on get the new default. | The default is applied when a file is created. |
| A file is replaced with a new version | It keeps its status and, if public, its link. | The status belongs to the file. |
| A member uploads into a public folder | The new file has the default status and is not public. It is not listed in the folder's public gallery. | The default never allows public use. |
| An owner sets an allowing status on that file | 409 CONFLICT, reason VISIBILITY_CHANGE, becomePublic 1. With confirmVisibilityChange: true it is public through the folder. | Making a file public is never silent. |
| An allowing status is set on a file outside any public folder | It works without a confirmation. The file stays restricted. | The status only makes sharing possible. |
| A non-allowing status is set on a file that is public itself | The API sets it at once, without a confirmation; the app asks first. The link answers 404, the file's general access is restricted, and the file is in restrictedFileIDs. | A file is public only while its status allows it. |
The status of such a file is cleared (statusID: null) | The same: the link stops. | A file without a status is never public. |
| That file gets an allowing status again | It stays restricted. Sharing it again gives the same link as before. | A stopped own link comes back only by sharing again. |
| A non-allowing status is set on a file that is public through a public folder | Its link stops and it is in restrictedFileIDs. It leaves the folder's public gallery. | The folder shares only files whose status allows public use. |
| That file gets an allowing status again | 409 CONFLICT, reason VISIBILITY_CHANGE. Once confirmed, it is public through the folder again, at the same link. | The folder is still shared, and making a file public is never silent. |
| "Allows public use" is turned off for a status with public files | Every public file with the status becomes restricted at once. Files of other workspaces and the organization folder are not touched, also when their status has the same name. | The status decides for all its files, and only its own workspace or organization folder has them. |
| It is turned on again | Files that were public themselves stay restricted. Files in public folders become public again, after VISIBILITY_CHANGE is confirmed. | Own sharing was withdrawn; the folders are still shared. |
| "Allows public use" is turned on for a status whose files sit in a public folder | 409 CONFLICT, reason VISIBILITY_CHANGE, with the count in becomePublic. Nothing changes until confirmed. | Making files public is never silent. |
| The same request also renames the status | The rename is refused with it. Nothing changes. | A refused request changes nothing. |
| A status is deleted while files with it are public | Their links stop. restrictedFileCount counts them. No confirmation is asked by the API. | Deleting can only stop links. |
| A status is deleted while files with it are in the trash | They lose the status too and come back from the trash without a status, restricted. They are not counted in restrictedFileCount. The app names them before the deletion, for example "4 files will have no status, and so will 2 files in the trash." | A trashed file is not public, so no link stopped. The confirmation counts every file that loses the status (trashedFileCount). |
A plain member, or any credential, reads trashedFileCount | null. | Only those who may delete the status read it: an owner or admin of the workspace or organization folder in a browser. |
| A status is deleted and a new one is added with the same name | The new status has a new ID. No file has it. | Deletion cannot be undone. |
| A status in the middle of the list is deleted | The statuses after it move up one position. | Positions have no gaps. |
| A reorder leaves out a status, names one twice or names an unknown one | 422 VALIDATION_FAILED on statusIDs. The order stays. | A reorder names every status exactly once. |
| Someone adds a status while another person reorders from an older page | The reorder is refused with 422, because it does not name the new status. | Same rule. Reload and reorder again. |
| Two admins make two different statuses the default at the same moment | Both succeed, one after the other. The later one is the default. | Changes to the list are handled one at a time. |
| Two admins add a status with the same name at the same moment | One succeeds. The other gets 409 CONFLICT, reason NAME_TAKEN. | Same. |
| A batch of files includes one that is in the trash | 409 CONFLICT, reason IN_TRASH. No file changes. | A status change is all or nothing. Restore the file or leave it out. |
| A batch includes an unknown file, or a file of another workspace | 404 NOT_FOUND. No file changes. | All files must be in the workspace or organization folder of the request. |
fileIDs is empty or names 101 files | 422 VALIDATION_FAILED on fileIDs. | 1 to 100 files per request. |
fileIDs names the same file twice | It counts once. | Each file is changed once. |
The request has no statusID | 422 VALIDATION_FAILED. The status is not cleared. | Only an explicit null clears. |
statusID is a status of another workspace, of the organization folder (for workspace files), of a workspace (for organization folder files) or of another organization | 422 VALIDATION_FAILED on statusID. No file changes. | A file carries only a status of its own workspace or organization folder. |
| A status is deleted while someone has its picker open | Choosing it answers 422 on statusID. The app says "That status no longer exists. Choose another." | The status is gone. |
| A member with the workspace role admin sets a status on a workspace file | It works. | The effective workspace role counts for workspace files. |
| That member sets a status on an organization folder file | 403 FORBIDDEN. | Organization folder files need the organization role owner or admin. |
A credential with only files:write sets a status | 403 FORBIDDEN, reason INSUFFICIENT_SCOPE, requiredScopes ["files:approve"]. | No write scope includes files:approve. |
A credential with files:approve whose member was demoted to member | 403 FORBIDDEN. | The role is checked at each use. |
A credential with files:approve whose member has no verified email | 403 EMAIL_NOT_VERIFIED. | A status change through a credential needs a verified email. |
A credential with only files:approve lists the statuses | 403 FORBIDDEN, reason INSUFFICIENT_SCOPE. | Reading needs files:read. |
| In the app, more than 100 files are selected and the status would make some public | The app asks once, before anything changes, with the total over the whole selection, for example "101 files will become public." If you confirm, every file gets the status. If you cancel, no file does. | The app previews every batch of 100 with dryRun before it sends any. |
| In the app, a status that does not allow public use is set on a public file | The app asks "Change who can open these files?" and says "1 public link will stop working." before it sets the status. | The app asks whenever a change starts or stops public links. The API stops links without a confirmation. |
A request with dryRun: true names a file in the trash, an unknown file or an unknown status | It is refused exactly as the change would be: 409 IN_TRASH, 404 NOT_FOUND or 422 on statusID. | A preview checks everything the change checks. |
A request with dryRun: true would make files in a public folder public | 200. The files are named in madePublicFileIDs. Nothing changes. | A preview needs no confirmation, because it changes nothing. |
A request sends both dryRun: true and confirmVisibilityChange: true | It is a preview. Nothing changes. | dryRun decides. |
| A file changes between a preview and the change | The change does what is true at that moment. Unconfirmed, it is still refused with VISIBILITY_CHANGE if it would make files public. | A preview answers for the moment it is asked. |
| A deleted workspace's status list is read or changed | 404 NOT_FOUND until the workspace is restored. The restore brings it back with its statuses as they were. | Nothing of a deleted workspace is reachable. See Workspaces. |
| A plain member and an owner read the same list | They read the same fileCount, publicFileCount and noStatusFileCount. Only trashedFileCount differs. | The counts cover only that workspace or organization folder, which both can read. |
status= in a listing is neither an ID nor none | 422 VALIDATION_FAILED on status. | The filter takes a status ID or none. |
status= names a deleted or foreign status | An empty listing. | No file has it. |
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 | Someone who is not an owner or admin of the workspace or organization folder manages its list or sets a status. A credential's member is no longer an owner or admin. | Ask an owner or admin. |
FORBIDDEN, reason SESSION_REQUIRED | 403 | A credential adds, changes, reorders or deletes a status. | A person does this in a browser. |
FORBIDDEN, reason INSUFFICIENT_SCOPE | 403 | A credential without files:approve sets a status, or one without files:read reads the list or the counts of a place. details.requiredScopes names the scope. | Use a credential with that scope. |
EMAIL_NOT_VERIFIED | 403 | A credential sets a status and its member's email is not verified. | The member verifies their email address. |
NOT_FOUND | 404 | The organization or workspace is unknown, deleted or out of reach. The status to change or delete is unknown or of another workspace or the organization folder. A file in the batch is unknown or not in this workspace or organization folder. The folderID of a count is not a live folder of that workspace or organization folder. | Check the IDs. Read the list again. |
CONFLICT, reason NAME_TAKEN | 409 | Another status has the name, ignoring case. Message: "Another status has that name". | Choose another name. |
CONFLICT, reason DEFAULT_ALLOWS_PUBLIC | 409 | The change would leave the default status allowing public use. Message: "The status new uploads get cannot allow public use". | Keep the default a status that does not allow public use. |
CONFLICT, reason VISIBILITY_CHANGE | 409 | A status change would make files in public folders public and is not confirmed. details.becomePublic counts them. Nothing changed. | Show the count to a person, then repeat with confirmVisibilityChange: true. |
CONFLICT, reason IN_TRASH | 409 | A file in the batch is in the trash. Message: "The file is in the trash; restore it first". | Restore it, or leave it out. |
VALIDATION_FAILED | 422 | name breaks the naming rules; the workspace or organization folder has 50 statuses (details.field is statuses); statusIDs does not name every status of the list once; statusID is unknown or of another workspace or the organization folder; fileIDs is not 1 to 100 files; status in a listing is not an ID or none; folderID of a count is not an ID; the body is not the expected JSON. details.field names the field where there is one. | Correct the field. |
RATE_LIMITED | 429 | A credential passed its request limit. | Wait for Retry-After seconds. |
- A request from a browser session that changes something must come from the app itself. See The REST API.
- Making a file public while its status does not allow it answers
409 CONFLICT, reasonSTATUS_BLOCKS_PUBLIC. That refusal belongs to Sharing and public links. - See Errors for the shape of every error and
CONFLICTfor every reason.
Limits
| What | Value |
|---|---|
| Status name | 1 to 60 characters after trimming, no control characters, unique in the workspace or organization folder ignoring case |
| Statuses per workspace, and in the organization folder | 0 to 50 |
| Default statuses per workspace, and in the organization folder | At most 1; it never allows public use |
| Statuses on one file | 0 or 1 |
| Files in one status change | 1 to 100 |
| Files one status can be on | No limit |
| Page size of the status list | Not paged |
| Page size of the counts of one place | Not paged; one row per status |
See also Limits.
Questions and answers
What is a status for? It says what a file may be used for, and it decides whether the file may be public. Only a file whose status allows public use can be opened by anyone with its link.
Which statuses do we start with? Every new workspace and the organization folder start with "Approved for public use", which allows public use, "Internal use only", which new uploads get, and "Not approved".
Can we rename them or make our own? Yes. Owners and admins of a workspace manage its statuses on its page "Statuses", in the workspace's settings navigation. Organization owners and admins manage the organization folder's on Settings > Organization folder and workspaces > Organization folder > Statuses. A workspace or the organization folder has up to 50.
Does each workspace have its own statuses? Yes. Every workspace has its own list, and so does the organization folder. Changing one changes nothing in the others.
Does "Approved for public use" make a file public? Not by itself. It makes sharing possible. An owner or admin still shares the file or a folder above it. The one exception is a file that already sits in a public folder: there the app asks "Change who can open these files?" first, and the file is public once you confirm.
Why can't I set a status? Only owners and admins set statuses. In a workspace that includes members who are owner or admin of that workspace.
I uploaded the file. Why can't I approve it myself? Approving decides what may become public. That is kept with owners and admins, whoever uploaded the file.
What status does a new upload get? The default status of its workspace or organization folder, marked "New uploads" in settings. In a new workspace or organization folder that is "Internal use only". Without a default, uploads start with no status.
Why can't the default status allow public use? So that no upload is public at once. Without this rule, a file dropped into a public folder would be public before anyone looked at it.
I want new uploads to be public right away. Can I? No. Every file needs someone with the right to set statuses to give it a status that allows public use.
What happens to public links when I change a file's status? If the new status does not allow public use, or you clear the status, the link stops at once. If it allows public use, nothing stops. The app asks first, saying how many public links will stop working.
I set the status back. Why is the link still dead? A file's own link that a status change stopped does not return by itself. Share the file again. It gets the same link it had. Only files in a public folder get their link back with the status, after you confirm.
What happens to files when I delete a status? They stay, without a status. Any of them that was public stops being public. The app tells you how many files and public links are affected before you confirm.
Can I undo deleting a status? No. You can add a status with the same name, but it is a new status. Set it on the files again and share again what should be public.
Can I set a status on many files at once? Yes. Select them and choose "Set status", or use "Set status" on a folder to label everything in it and below it. Through the API one request takes up to 100 files.
Can I see what a status change will do before I make it?
Yes. The app asks before any change that makes files public or stops public
links, with the totals for all the files. Through the API or MCP, send the
request with dryRun: true: it changes nothing and names the files that
would change, become public and stop being public.
If I set a status on a folder, do new files in it get that status? No. The status is set once on the files that are there. A file moved in later keeps its own status, and a new upload starts with the default status.
Does a file keep its status when I replace it with a new version? Yes. The status belongs to the file, not to the version.
Does moving a file change its status? No.
How do I find all files that are not approved yet? Use "Filter" > "Status" in a listing and choose the status, or "No status". The result covers every folder of the open workspace or organization folder.
Can I search for a status name? No. Search looks at names, descriptions, captions, alt text, text fields and tags. Use the Status filter.
What do the numbers in the "Statuses" card count? The live files per status in the place you have open: the open folder and every folder below it, or the whole workspace or organization folder at its top level. The card names that place in its corner.
Can I get the counts for one folder instead of the whole workspace?
Yes. Open the folder: the "Statuses" card counts it and the folders below
it. Through the API and MCP, workspace_files_status_count and
library_files_status_count count one workspace or the organization folder,
or with folderID one folder and every folder below it.
Where do I see the counts for the whole organization?
Nowhere in one number: each workspace and the organization folder count
their own files. The table "Statuses" on a workspace's "Statuses" settings
page, or on Settings > File spaces > Organization
folder > Statuses, counts that workspace or the organization folder.
Through the API, each status list reads fileCount for each status.
Can an agent set statuses?
Yes, with a credential that holds files:approve and belongs to an owner or
admin with a verified email. It uses workspace_files_status_set or
library_files_status_set.
Can an agent with files:write set statuses?
No. files:write does not include files:approve. The call answers
403 FORBIDDEN with reason INSUFFICIENT_SCOPE.
Can an agent create, rename or delete statuses? No. The lists are managed by a person in a browser.
What is VISIBILITY_CHANGE?
The refusal you get when a status change would make files public through a
public folder. Nothing changed. Repeat the request with
confirmVisibilityChange: true to go ahead.
What is restrictedFileIDs in the answer?
The files whose public link stopped because of the status you set.
Can a suggestion change a status? No. Suggestions tag, move, rename and describe files. They never change statuses or general access.
Can a file have two statuses? No. One or none. For more labels use fields and tags.
Is anyone notified when a status changes? No email is sent. The change is recorded in the audit trail.