Talewright Docs Open the app

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.

ActionWhoSessionCredential (scope)
Read a workspace's status listEveryone who can read the workspaceYesYes (files:read)
Read the organization folder's status listEvery member of the organizationYesYes (files:read)
See a file's statusEveryone who can read the fileYesYes (files:read)
Filter files by statusEveryone who can read the filesYesYes (files:read)
Count the files of one workspace, the organization folder or one folder by statusEveryone who can read the filesYesYes (files:read)
Add, rename, reorder or delete a workspace's statuses, change whether one allows public use or is the defaultEffective workspace owner or adminYesNo
Add, rename, reorder or delete the organization folder's statuses, change whether one allows public use or is the defaultOrganization owner or adminYesNo
Set or clear the status of files in a workspaceEffective workspace owner or adminYesYes (files:approve)
Set or clear the status of files in the organization folderOrganization owner or adminYesYes (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:write does 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 FORBIDDEN with details.reason SESSION_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 answers 404 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:

NameAllows public useDefault for new uploads
Approved for public useYesNo
Internal use onlyNoYes
Not approvedNoNo
  • 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, reason DEFAULT_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_FAILED on statuses and the message "a file space has at most 50 statuses".
  • The answer is 201 with the new status.

The checks happen in this order. The first that fails decides the answer:

  1. Not signed in: 401 UNAUTHENTICATED.
  2. The workspace or organization is unknown or deleted, or you cannot read it: 404 NOT_FOUND.
  3. The body is not the expected JSON: 422 VALIDATION_FAILED.
  4. You are not an owner or admin of the workspace or organization folder: 403 FORBIDDEN.
  5. The name breaks the naming rules: 422 VALIDATION_FAILED on name.
  6. The workspace or organization folder already has 50 statuses: 422 VALIDATION_FAILED on statuses.
  7. Another status has the name, ignoring case: 409 CONFLICT, reason NAME_TAKEN.
  8. 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:

  1. Not signed in: 401 UNAUTHENTICATED.
  2. The workspace or organization is unknown or deleted, or you cannot read it: 404 NOT_FOUND.
  3. The body is not the expected JSON: 422 VALIDATION_FAILED.
  4. You are not an owner or admin of the workspace or organization folder: 403 FORBIDDEN.
  5. The new name breaks the naming rules: 422 VALIDATION_FAILED on name.
  6. The status is unknown or belongs to another workspace, the organization folder or another organization: 404 NOT_FOUND.
  7. The change would leave the default status allowing public use: 409 CONFLICT, reason DEFAULT_ALLOWS_PUBLIC.
  8. Another status has the new name: 409 CONFLICT, reason NAME_TAKEN.
  9. The change allows public use, that would make files public, and the request does not confirm it: 409 CONFLICT, reason VISIBILITY_CHANGE.
  10. Otherwise it is changed: 200 with 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_FAILED on statusIDs and 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 200 with restrictedFileCount: 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:

  1. Not signed in: 401 UNAUTHENTICATED.
  2. The workspace or organization is unknown or deleted, or you cannot read it: 404 NOT_FOUND.
  3. You are not an owner or admin of the workspace or organization folder: 403 FORBIDDEN.
  4. The status is unknown or belongs to another workspace, the organization folder or another organization: 404 NOT_FOUND.
  5. 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}, or null for "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 statusID null clears the status ("No status").
  • A file ID named twice counts once.
  • statusID must be present. A request without it is refused and clears nothing: only an explicit null clears.
  • The files must be live. If one of them is in the trash, the whole request is refused with 409 CONFLICT, reason IN_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_FOUND and 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_FAILED on statusID with 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:approve and a verified email address of the credential's member.
  • Setting a status does not need the file's lockVersion and does not move it.
  • The answer is 200 with:
    • dryRun: false for a change;
    • status: the status set, or null;
    • 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: true changes nothing and answers what it would do right now: the same 200 answer, with dryRun: true.
  • changedFileIDs names the files whose status would change, madePublicFileIDs the files that would become public and restrictedFileIDs the files whose public link would stop.
  • Nothing is set: no status, no public link, no lockVersion and 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, fileIDs and files in the trash.
  • A preview needs no confirmVisibilityChange and never answers VISIBILITY_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_CHANGE when 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.

  1. Not signed in, or an invalid credential: 401 UNAUTHENTICATED.
  2. A credential without files:approve: 403 FORBIDDEN, reason INSUFFICIENT_SCOPE, with details.requiredScopes ["files:approve"].
  3. The workspace or organization is unknown, deleted or out of your reach: 404 NOT_FOUND.
  4. The body is not the expected JSON, for example statusID is missing: 422 VALIDATION_FAILED.
  5. You are not an owner or admin there: 403 FORBIDDEN.
  6. A credential whose member has no verified email: 403 EMAIL_NOT_VERIFIED.
  7. The status is unknown or not of this workspace or organization folder: 422 VALIDATION_FAILED on statusID.
  8. fileIDs names no file or more than 100: 422 VALIDATION_FAILED on fileIDs, with the message "name 1 to 100 files".
  9. A file is unknown or not in this workspace or organization folder: 404 NOT_FOUND.
  10. A file is in the trash: 409 CONFLICT, reason IN_TRASH.
  11. The status would make files public and the request neither confirms it nor is a dryRun: 409 CONFLICT, reason VISIBILITY_CHANGE.
  12. Otherwise the status is set, or with dryRun only 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.
  • restrictedFileIDs in 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 404 like 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, reason VISIBILITY_CHANGE, and changes nothing. This applies to setting an allowing status on files, and to turning "allows public use" on for a status.
  • details.becomePublic counts the files that would become public. details.stopPublic is 0 and details.publicVia is null for a status change.
  • Repeating the same request with confirmVisibilityChange: true carries 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.
  • trashedFileCount is 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 is null.

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 fileCount 0.
  • noStatusFileCount is 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 own fileCount, 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, or status=none for files without a status.
  • Any other value answers 422 VALIDATION_FAILED on status.
  • 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 with 422.
  • 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.deleted and file_status.reordered for the list, and file.status_changed once 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

  1. Choose "Add status".
  2. The dialog "Add status" has the field "Name" and the checkbox "Allows public use" with the text "Files with it can be shared publicly."
  3. "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:

ItemWhat 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.

  1. 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.
  2. In the toolbar "Selected files", choose "Set status". It lists "No status" and every status.
  3. 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.

  1. Choose "Set status" in the folder's row menu, or at the bottom of the card "Statuses" in the folder's "Details".
  2. The dialog "Status of {folder}" has the picker "Status".
  3. 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."
  4. "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.

MessageWhen
"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 areThe card namesThe card counts
Inside a folder of a workspaceThe folderThe files in that folder and in every folder below it
The top level of a workspaceThe workspaceEvery file of the workspace, whichever folder it is in
Inside a folder of the organization folderThe folderThe 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.

OperationCapability IDMCP toolScope
GET /v1/workspaces/{workspaceID}/file-statusesworkspace.file_statuses.listworkspace_file_statuses_listfiles:read
GET /v1/organizations/{organizationID}/library/file-statuseslibrary.file_statuses.listlibrary_file_statuses_listfiles:read
GET /v1/workspaces/{workspaceID}/files/status-countsworkspace.files.status.countworkspace_files_status_countfiles:read
GET /v1/organizations/{organizationID}/library/files/status-countslibrary.files.status.countlibrary_files_status_countfiles:read
POST /v1/workspaces/{workspaceID}/files/statusworkspace.files.status.setworkspace_files_status_setfiles:approve
POST /v1/organizations/{organizationID}/library/files/statuslibrary.files.status.setlibrary_files_status_setfiles:approve
POST /v1/workspaces/{workspaceID}/file-statusesworkspace.file_statuses.createnonesession only
PATCH /v1/workspaces/{workspaceID}/file-statuses/{statusID}workspace.file_statuses.updatenonesession only
PUT /v1/workspaces/{workspaceID}/file-statuses/orderworkspace.file_statuses.reordernonesession only
DELETE /v1/workspaces/{workspaceID}/file-statuses/{statusID}workspace.file_statuses.deletenonesession only
POST /v1/organizations/{organizationID}/library/file-statuseslibrary.file_statuses.createnonesession only
PATCH /v1/organizations/{organizationID}/library/file-statuses/{statusID}library.file_statuses.updatenonesession only
PUT /v1/organizations/{organizationID}/library/file-statuses/orderlibrary.file_statuses.reordernonesession only
DELETE /v1/organizations/{organizationID}/library/file-statuses/{statusID}library.file_statuses.deletenonesession only
  • files:approve does not include reading. A credential that should look up statuses and files and then set statuses needs files:read (or files:write) as well as files:approve.
  • GET .../files?status={statusID} and GET .../files?status=none filter 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
}
  • items holds every status of that workspace or organization folder in list order, each with id, name and fileCount.
  • The answer is not paged.
  • Over MCP the arguments are workspaceID (or organizationID for the organization folder) and the optional folderID.
  • To list the files behind a number, use the file listing with status= and under={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"]
}
PropertyValue
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.
confirmVisibilityChangetrue to go ahead although files in public folders become public.
dryRuntrue 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": true the 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 dryRun first and add up the lists.
  • The same call over MCP is workspace_files_status_set or library_files_status_set, with workspaceID or organizationID added 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": true is not refused. It answers 200 and names the file in madePublicFileIDs, so you can ask before you try.
  • Show the count to the person you act for. Repeat the request with "confirmVisibilityChange": true only when making those files public is what they want.
  • After the confirmed request the file reads public: true with its publicURL.

What the session-only operations take and return

OperationBodySuccess
Add{"name": "...", "allowsPublic": true | false}, both required201 with the status
ChangeAny of name, allowsPublic, isDefault, confirmVisibilityChange200 with the status
Reorder{"statusIDs": ["...", "..."]}, every status once200 with the list and noStatusFileCount
Deletenone200 with {"restrictedFileCount": n}

Edge cases

SituationWhat happensWhy
A status named "Licensed" exists and someone adds "licensed" to the same list409 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 folderIt works.Each list is separate.
A status is renamed to its own name in another caseIt works.It conflicts with no other status.
The name is blank, 61 characters long or ends in a line break422 VALIDATION_FAILED on name.The naming rules.
A workspace or the organization folder with 50 statuses adds one more422 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 status403 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 statusesIt works.The effective workspace role counts for a workspace's list.
That member manages the organization folder's statuses403 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 ofIt 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 folder404 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 list404 NOT_FOUND, as for an unknown workspace or organization.Outsiders cannot tell it exists.
A credential adds, changes, reorders or deletes a status403 FORBIDDEN, reason SESSION_REQUIRED.A list is managed by a person in a browser.
The default status is asked to allow public use409 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 default409 CONFLICT, reason DEFAULT_ALLOWS_PUBLIC.Same rule.
One request sets isDefault: true and allowsPublic: false on a status that allows public useIt 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 defaultThe first loses the mark.At most one default.
The default is switched offNo status is the default. New uploads start without a status.A default is optional.
The default status is deletedThe same: no default afterwards. Its files are left without a status.Deleting does not pick a new default.
Every status is deletedThe 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 changedFiles 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 versionIt keeps its status and, if public, its link.The status belongs to the file.
A member uploads into a public folderThe 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 file409 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 folderIt 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 itselfThe 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 againIt 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 folderIts 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 again409 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 filesEvery 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 againFiles 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 folder409 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 statusThe rename is refused with it. Nothing changes.A refused request changes nothing.
A status is deleted while files with it are publicTheir 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 trashThey 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 trashedFileCountnull.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 nameThe new status has a new ID. No file has it.Deletion cannot be undone.
A status in the middle of the list is deletedThe statuses after it move up one position.Positions have no gaps.
A reorder leaves out a status, names one twice or names an unknown one422 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 pageThe 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 momentBoth 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 momentOne succeeds. The other gets 409 CONFLICT, reason NAME_TAKEN.Same.
A batch of files includes one that is in the trash409 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 workspace404 NOT_FOUND. No file changes.All files must be in the workspace or organization folder of the request.
fileIDs is empty or names 101 files422 VALIDATION_FAILED on fileIDs.1 to 100 files per request.
fileIDs names the same file twiceIt counts once.Each file is changed once.
The request has no statusID422 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 organization422 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 openChoosing 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 fileIt works.The effective workspace role counts for workspace files.
That member sets a status on an organization folder file403 FORBIDDEN.Organization folder files need the organization role owner or admin.
A credential with only files:write sets a status403 FORBIDDEN, reason INSUFFICIENT_SCOPE, requiredScopes ["files:approve"].No write scope includes files:approve.
A credential with files:approve whose member was demoted to member403 FORBIDDEN.The role is checked at each use.
A credential with files:approve whose member has no verified email403 EMAIL_NOT_VERIFIED.A status change through a credential needs a verified email.
A credential with only files:approve lists the statuses403 FORBIDDEN, reason INSUFFICIENT_SCOPE.Reading needs files:read.
In the app, more than 100 files are selected and the status would make some publicThe 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 fileThe 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 statusIt 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 public200. 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: trueIt is a preview. Nothing changes.dryRun decides.
A file changes between a preview and the changeThe 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 changed404 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 listThey 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 none422 VALIDATION_FAILED on status.The filter takes a status ID or none.
status= names a deleted or foreign statusAn empty listing.No file has it.

Errors

CodeStatusWhenWhat to do
UNAUTHENTICATED401Not signed in, or an invalid credential.Sign in or use a valid credential.
FORBIDDEN403Someone 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_REQUIRED403A credential adds, changes, reorders or deletes a status.A person does this in a browser.
FORBIDDEN, reason INSUFFICIENT_SCOPE403A 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_VERIFIED403A credential sets a status and its member's email is not verified.The member verifies their email address.
NOT_FOUND404The 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_TAKEN409Another status has the name, ignoring case. Message: "Another status has that name".Choose another name.
CONFLICT, reason DEFAULT_ALLOWS_PUBLIC409The 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_CHANGE409A 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_TRASH409A 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_FAILED422name 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_LIMITED429A 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, reason STATUS_BLOCKS_PUBLIC. That refusal belongs to Sharing and public links.
  • See Errors for the shape of every error and CONFLICT for every reason.

Limits

WhatValue
Status name1 to 60 characters after trimming, no control characters, unique in the workspace or organization folder ignoring case
Statuses per workspace, and in the organization folder0 to 50
Default statuses per workspace, and in the organization folderAt most 1; it never allows public use
Statuses on one file0 or 1
Files in one status change1 to 100
Files one status can be onNo limit
Page size of the status listNot paged
Page size of the counts of one placeNot 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.