# 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](sharing.md#the-strict-rule).

## 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](../organizations/members-and-roles.md#workspace-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: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](../agents/credentials.md#filesapprove).
- 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](../reference/permissions.md#statuses-and-fields-of-a-workspace).

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

| 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](sharing.md#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](#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](sharing.md#the-public-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](#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](#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](../agents/rest-api.md#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](image-delivery.md#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](sharing.md#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](sharing.md#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](#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](organizing.md).
- 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](organizing.md).

### Elsewhere

- The field list of a workspace or the organization folder presents status as
  its built-in first field. See [Fields and
  tags](fields-and-tags.md#custom-fields).
- A suggestion (library proposal) cannot change a status. See
  [Suggestions](library-and-suggestions.md#suggestions).
- An organization export lists each workspace's and the organization
  folder's statuses and each file's status. See
  [Export](../organizations/export.md#the-manifest).
- Every change is recorded in the
  [audit trail](../reference/audit-trail.md#statuses-and-fields):
  `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](../organizations/workspaces.md#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](#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:

| 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](#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-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](#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.**

| 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](#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](#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](#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: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

```sh
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`).

```json
{
  "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.

```sh
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/files/status-counts?folderID=$FOLDER_ID" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

```json
{
  "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](organizing.md).

### Setting a status

```sh
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"
  }'
```

```json
{
  "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": 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](#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](../agents/mcp.md#set-a-status).

### When files would become public

Setting "Approved for public use" on a file that sits in a public folder is
refused first:

```json
{
  "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

| 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](../organizations/workspaces.md#restoring). |
| 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](../agents/rest-api.md#signing-in-with-a-browser-session).
- 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](sharing.md#the-strict-rule).
- See [Errors](../reference/errors.md) for the shape of every error and
  [`CONFLICT`](../reference/errors.md#conflict-409) for 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](../reference/limits.md#statuses-and-fields).

## 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](fields-and-tags.md).

**Is anyone notified when a status changes?**
No email is sent. The change is recorded in the audit trail.

## Related pages

- [Sharing and public links](sharing.md)
- [Image delivery](image-delivery.md)
- [Fields and tags](fields-and-tags.md)
- [The organization folder and suggestions](library-and-suggestions.md)
- [Files & Assets overview](overview.md)
- [Uploading](uploading.md), [Versions and history](versions.md) and
  [Trash and restore](trash.md)
- [Folders, moving and finding](organizing.md)
- [Credentials and scopes](../agents/credentials.md#filesapprove)
- [MCP](../agents/mcp.md#statuses-and-fields) and
  [The REST API](../agents/rest-api.md)
- [Roles and permissions](../reference/permissions.md)
- [Audit trail](../reference/audit-trail.md#statuses-and-fields)
- [Limits](../reference/limits.md#statuses-and-fields) and
  [Errors](../reference/errors.md)

