Talewright Docs Open the app

Files & Assets overview

Summary

Files & Assets is where a team keeps its files: logos, photos, videos, fonts, design files, documents. It is the one place the people of an organization, and the agents that work for them, go to find the current version of a file, check whether it may be used, and get it.

Files live in workspaces, and in one organization folder that the whole organization shares. Every file keeps its history: replacing a file adds a version instead of losing the old one. Files are organized in folders, described with details, tags and fields, labeled with a status, and can be shared with anyone through a public link.

This page explains the ideas the other pages build on, takes you through the file browser, shows at a glance who can do what, and says which page covers which feature.

Who can do what

The table shows the whole area at a glance. "Member" is a plain member. "Owner or admin" in a workspace means the effective role there: an organization owner or admin, or a member who is owner or admin of that workspace. In the organization folder it means the organization role.

ActionWorkspace: memberWorkspace: owner or adminOrganization folder: memberOrganization folder: owner or adminCredential
Browse, search, open and download filesYesYesYesYesfiles:read
Star favoritesYesYesYesYesfiles:read
Upload files and replace themYesYesNoYesfiles:write
Create, rename and move foldersYesYesNoYesfiles:write
Rename and move files, edit details, tags and field valuesYesYesNoYesfiles:write
Move to the trash and restoreYesYesNoYesfiles:write
Set a file's statusNoYesNoYesfiles:approve
Make a file or folder public, or restricted againNoYesNoYesNo. A person in a browser.
Make files public by moving or restoring themNoYesNoYesfiles:write and files:approve
Delete for good, empty the trashNoYesNoYesNo. A person in a browser.
Manage the statuses and fields of the workspace or organization folderNoYesNoYesNo. A person in a browser.
Rename or delete a tag of the workspace or organization folderNoYesNoYesfiles:write
  • In a workspace, every member works with the files. In the organization folder, every member of the organization reads, and only owners and admins change.
  • Three things are reserved for owners and admins everywhere: deciding a file's status, deciding what is public, and deleting for good.
  • A credential acts for one member and can never do more than that member. It reaches the workspaces it lists, and the organization folder of its organization.
  • Someone who cannot reach a workspace or an organization gets 404 NOT_FOUND for everything in it.
  • Every action, with every role and scope, is in Roles and permissions.

How it works

Workspaces and the organization folder

  • An organization has one or more workspaces. A workspace is one brand, client or business. See Workspaces.
  • Each workspace has its own files, folders, tags, statuses, fields and trash.
  • An organization also has exactly one organization folder. The organization folder is a shared place for files that every workspace uses, such as the company logo.
  • The organization folder has its own files, folders, tags, statuses, fields and trash, like a workspace.
  • A file lives in exactly one place: one workspace, or the organization folder. The product documentation calls that place the file's file space where it needs one word for both.
  • A file cannot be moved from one workspace to another, or between a workspace and the organization folder. See Folders, moving and finding.
  • Statuses and fields are not shared: each workspace and the organization folder has its own list of statuses and its own fields. A file only carries a status and field values of its own workspace or organization folder.
  • The API calls the organization folder the library. More about it is in The organization folder and suggestions.

How the two differ:

A workspaceThe organization folder
How manyOne or more per organizationOne per organization
Who readsThe workspace's members, and the organization's owners and adminsEvery member of the organization
Who changesEveryone who reads itThe organization's owners and admins
Reached through the API at/v1/workspaces/{workspaceID}/.../v1/organizations/{organizationID}/library/...
Can be deletedYes, and restored for 30 daysOnly with the organization

Files

  • A file is a named item with one or more versions of bytes.
  • A file has an ID that never changes. Renaming, moving, replacing and restoring keep the ID.
  • A file has a name. Names need not be unique: two files in one folder can have the same name.
  • A file sits in one folder, or at the top level.
  • A file carries details: a description, a caption, alt text and tags. See Folders, moving and finding and Fields and tags.
  • A file carries values of its workspace's or organization folder's fields, and one of its statuses or none. See Statuses.
  • A file is restricted or public. See Sharing and public links.
  • A file is live or in the trash. See Trash and restore.
  • A file records who created it and when, and who last updated it and when.

Versions

  • The bytes of a file are a version. A version never changes.
  • Uploading a new file makes version 1. Replacing the file adds version 2, and so on. The newest is the current version.
  • Earlier versions are kept and can be downloaded.
  • Everything else belongs to the file, not to a version: its name, folder, status, details and public link stay when the file is replaced.
  • See Versions and history.

Folders

  • Each workspace, and the organization folder, has one tree of folders.
  • Folders nest up to 16 levels deep.
  • A folder's name is unique among the folders beside it.
  • A folder can be public. Its files that are approved for public use are then public too.
  • See Folders, moving and finding.

What happens to a file over time

  1. It is uploaded. The bytes are checked: size, type, whether the file opens, and malware. Only then does the file exist. See Uploading.
  2. It gets previews. A thumbnail and a preview are made where the type allows, and a playable copy for videos that browsers cannot play.
  3. It is organized. It is put in a folder, named, described and tagged.
  4. It gets a status. An owner or admin says whether it may be used. A new file starts with the default status of its workspace or organization folder, which never allows public use.
  5. It may be shared. With a status that allows public use, an owner or admin can make it public, or it becomes public through a public folder.
  6. It is replaced. New bytes become a new version. Links keep working.
  7. It is removed. It goes to the trash, can be restored for 30 days, and is then deleted for good with every version.

Rules that hold everywhere

  • Nothing is public by accident. A file is public only while its status allows public use and it, or a folder above it, is shared with anyone who has the link. An upload is never public at once.
  • Nothing is lost by accident. Removing goes through the trash. Replacing keeps the earlier version. Only owners and admins delete for good.
  • Nobody overwrites anybody. A change to a file or folder names the state it was based on. If someone else changed it first, the change is refused and nothing is overwritten.
  • Bytes are kept exactly. What is downloaded is what was uploaded.
  • People outside see nothing. Someone without access cannot tell whether a workspace, a folder or a file exists.
  • Agents work under the same rules. An agent acts for one member, with the scopes it was given. Public access and permanent deletion stay with a person in a browser.

How the pages fit together

PageCovers
UploadingEvery way to upload, the accepted types, the checks, the upload tray, previews and video playback
Folders, moving and findingFolders, moving, renaming, details, favorites, search, filters, sorting, and what happens when two people change the same thing
Versions and historyReplacing a file, what stays and what changes, the history, earlier versions
Trash and restoreMoving to the trash, restoring, deleting for good, the 30 days
StatusesThe statuses of each workspace and the organization folder, setting them, and how a status decides whether a file can be public
Sharing and public linksGeneral access of files and folders, public links, public folders and their galleries
Image deliveryResized and reformatted images from a public link
Fields and tagsThe fields of each workspace and the organization folder, their values on files, and tags
The organization folder and suggestionsThe organization folder, and batches of suggested changes that a person reviews
DownloadingDownloading a file, a version, a folder or a selection, and temporary links

Around them:

PageCovers
WorkspacesCreating, deleting and restoring workspaces, and who reaches them
Members and rolesOwners, admins and members
ExportA copy of all of an organization's current files
Credentials and scopesAPI keys, and what files:read, files:write and files:approve allow
MCP and The REST APIHow agents and programs work with files
Roles and permissionsEvery action against every role and scope
LimitsEvery size, count and time window
ErrorsEvery error code
Audit trailWhat is recorded about changes to files
GlossaryThe words used on these pages

In the app

Opening Files & Assets

  • "Files & Assets" is in the sidebar. It opens the files of the workspace you are in.
  • The keys G then F go there from anywhere in a workspace.
  • The command palette offers "Go to Files & Assets" and "Go to Organization folder".
  • The workspace you are in is chosen in the workspace switcher at the top of the sidebar.

The layout

A Files & Assets page has three parts, from left to right:

  1. The navigation. "All files", "Suggestions" and "Trash" of the open workspace or organization folder, then "Favorites", then the tree "Folders". "Suggestions" shows a number: the open suggestions plus the duplicate groups you have not hidden. See The Suggestions page.
  2. The listing. The folders and files of the place you have open, with the toolbar above it.
  3. Details. Cards about the open folder, or about the workspace or organization folder at the top level.

On a narrow window the navigation folds into a row with a "Folders" button, and "Details" opens from a button in the toolbar.

The folder tree

  • The root of the tree is the organization, which is its organization folder: clicking its name opens the organization folder, and its arrow closes or opens the entries below it.
  • Below it comes one workspace folder for each of your workspaces in that organization, with its folders, then the organization folder's own folders.
  • The tree is how you go to the organization folder and to your other workspaces.
  • Files and folders can be dragged onto a folder in the tree to move them.
  • See Getting around.

The listing

  • Grid or list. The view switch offers "Grid view" and "List view". The grid shows folders as cards and files as tiles with thumbnails. The list shows one row per item with the columns "Name", "Status", "Size" and "Modified".
  • Folders first. Folders are always listed before files.
  • Badges. A file shows its status. A file or folder that anyone with the link can open shows "Public" or "Public via folder".
  • The breadcrumb above the listing, "Folder path", shows where you are and lets you go up.
  • The organization folder's top level also lists your workspaces, before the organization folder's own folders. Clicking one opens that workspace's files.
  • See Grid and list.

The toolbar

  • "New folder" and "Upload", where you may change files.
  • "Filter": by type, status, field, duplicates and tag.
  • "Sort": "Recently updated" or "Name".
  • "Search files": looks through the whole workspace or organization folder.
  • The view switch.
  • See Searching and Filtering and sorting.
  • Every file and folder has a menu: "Open", "Download", "Share", "Make public" or "Make restricted", "Copy link", "Rename", "Move", "Move to parent folder", "Set status", "Add to favorites" and "Move to trash". You see the items you may use.
  • Where you may change files, items have checkboxes. A file's checkbox shows when you point at the file, and so does a folder card's, in place of its icon. A folder's row in the list view always shows its checkbox. With something selected, a bar at the bottom of the listing offers "Select all", "Download", "Move", "Set status", "Set field" and "Move to trash" for all of it.
  • See The menu of a file or folder.

The Details pane

Beside the listing, "Details" describes what you have open:

  • a card for each open suggestion, with "Review",
  • "Folder details": the name, the number of folders and files, and who can open it ("Restricted", "Every workspace", "Public" or "Public, from {folder}"),
  • inside a folder: "About" with the folder's name, "Sharing" and "Location",
  • "Statuses": how many files of the place you have open have each status. Inside a folder that is the folder and every folder below it; at the top level it is the whole workspace or organization folder. The card names the place in its corner. Inside a folder, owners and admins find "Set status" at its bottom. See Statuses,
  • "People": who can open the workspace or the organization folder,
  • "Recent activity": the files changed last, here and below, with who changed them. A file that was not changed since its upload reads "added".

A file's page

Clicking a file opens its page.

  • At the top: the folders it is in, its name, and a star for your favorites.
  • If the same bytes exist elsewhere, a notice marked "Duplicate" under the name says "Same file as {name} in {place}", once per copy, with a link to each. "Hide" on the notice hides it for you alone. See The duplicate notice on a file's page.
  • Then the actions: "Download", "Replace file" and "Move to trash". You see the ones you may use.
  • Then the preview: the image, the first page of a PDF, or a video player. A photo or video fills the width of the page, never larger than the original. Other previews keep a fixed height. A file without a preview says "Preview unavailable".
  • Then "Details", under the preview: plain sections without cards, in two columns.
  • The left column is the section "Details": name, description, caption, alt text and tags, with "Save details".
  • The right column holds the other sections:
    • "Status": the file's status and whether it allows public use,
    • "Sharing": the general access and, while public, the public link,
    • "Fields": the fields of the file's workspace or organization folder, with "Save fields". The section shows only while that workspace or organization folder has fields,
    • "Location": where the file is, with "Move",
    • "Properties": "Type", "Size", "Dimensions", "Updated" and "Created".
  • Last, across both columns, "History": every version, each with "Download". It grows downward as versions are added.
  • On a narrow window "Details" is one column: the section "Details", then the sections of the right column, then "History".
  • The page stands centred in the work area. On a wide window it keeps its width and leaves the same space on both sides.

Tabs

The app has its own tabs above the work area, like the tabs of a browser.

  • "New tab" (Alt+T) opens another tab. "Close tab" (Alt+W) closes the current one.
  • "Next tab" (Alt+]) and "Previous tab" (Alt+[) switch between them.
  • Each tab is named after its page: "Files & Assets", "Organization folder", "Trash", "Organization folder trash", or the name of the open file.
  • You can keep a folder open in one tab and a file in another.
  • Uploads keep running whichever tab you look at.

The upload tray

  • The tray "Uploads" appears at the bottom of the window when you upload.
  • It lists every file with its status: "Waiting", "Uploading", "Verifying", "Ready", "Rejected", "Failed" or "Cancelled".
  • It stays while you move around the app and between its tabs.
  • See The upload tray.

What a member of the organization folder sees

Someone who may read the organization folder but not change it sees the same pages with fewer controls:

  • no "New folder", no "Upload", no checkboxes, no "Trash" link,
  • in a file's menu: "Open", "Download", "Share", "Copy link" and "Add to favorites",
  • on a file's page: "Download", and the details as text.

For agents

Where things are

Everything a person does with files in the app is an operation of the REST API, and most are MCP tools.

  • Workspace operations are under /v1/workspaces/{workspaceID}. Organization folder operations mirror them under /v1/organizations/{organizationID}/library.
  • Each operation has a capability ID, such as workspace.files.search or library.folders.create. The MCP tool has the same name with underscores: workspace_files_search.
  • An agent starts with workspaces_list, which returns the workspaces its credential reaches, each with its organizationID for the organization folder.
FamilyWorkspace pathDocumented in
Files: list, search, read, change, trash, restore/filesFolders, moving and finding, Trash and restore
Versions and content/files/{fileID}/versionsVersions and history, Downloading
Folders/foldersFolders, moving and finding
Tags/tagsFields and tags
Uploads/uploadsUploading
ZIP downloads/files/archiveDownloading
Favorites/favoritesFolders, moving and finding
Statuses and fields of the workspace or organization folder/file-statuses, /file-fieldsStatuses, Fields and tags
Status and field values of files/files/status, /files/fieldsStatuses, Fields and tags
General access/files/{fileID}/visibility, /folders/{folderID}/visibilitySharing and public links
Suggestions/library-proposalsThe organization folder and suggestions

What an agent can and cannot do

WithAn agent can
files:readList, search and read files and folders, read the statuses, fields and tags, read histories, download, ask for temporary links and ZIPs, read its uploads, manage its member's favorites
files:writeEverything above, and: upload, replace, create folders, rename, move, edit details, tags and field values, trash and restore, suggest changes. Renaming and deleting a tag only for a credential that acts for an owner or admin of the workspace or organization folder.
files:approveSet file statuses. Together with files:write: moves and restores that make files public. Only for a credential that acts for an owner or admin.
No scopeMake a file or folder public or restricted, delete for good, empty the trash, apply a suggestion, manage statuses and fields
  • A refusal for the last row is 403 FORBIDDEN with details.reason SESSION_REQUIRED, or HUMAN_APPROVAL_REQUIRED for applying a suggestion.
  • Bytes never travel through MCP. Uploads go to a temporary address with an ordinary HTTP PUT, and downloads come from a temporary link with an ordinary GET.

A first look around

curl -s "$TALEWRIGHT/v1/workspaces" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"

Take a workspace's id, then list what is at its top level:

curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE/folders" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"

curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files?root=true" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"

Each file in the answer looks like this, shortened:

{
  "id": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
  "name": "logo.png",
  "folderID": null,
  "folderPath": [],
  "description": null,
  "caption": null,
  "altText": "The Acme logo in blue",
  "tags": [{ "id": "0192f0aa-...", "name": "brand" }],
  "status": {
    "id": "0192e7c5-...",
    "name": "Approved for public use",
    "allowsPublic": true
  },
  "visibility": "restricted",
  "public": false,
  "publicVia": null,
  "lockVersion": 3,
  "previewStatus": "ready",
  "thumbnailURL": "https://...",
  "currentVersion": {
    "id": "0192f0b2-7a40-7133-9c88-5c9a3f4b0e23",
    "number": 1,
    "mime": "image/png",
    "sizeBytes": 20480,
    "digest": "sha256:9f2c..."
  },
  "createdAt": "2026-11-02T09:00:00Z",
  "updatedAt": "2026-11-10T14:30:00Z",
  "deletedAt": null,
  "purgeAfter": null
}
  • Reading one file adds fields, duplicates, duplicatesHidden, previewURL, publicURL and playbackStatus.
  • duplicatesHidden is true when the reader hid the warning about the file's duplicates. See Duplicate groups.
  • Every property is explained in MCP.
  • The same two listings for the organization folder are /v1/organizations/{organizationID}/library/folders and .../library/files?root=true.

Edge cases

SituationWhat happensWhy
Someone outside a workspace asks for its files, by any address404 NOT_FOUND, the same as for a workspace that does not exist.Outsiders cannot tell what exists.
An organization folder file's ID is used under a workspace's address, or the other way round404 NOT_FOUND.A file is reached only through the place it lives in.
A file of workspace A is asked for under workspace B, by someone who reaches both404 NOT_FOUND.The same rule.
A member of the organization who belongs to no workspace asks for the organization folder's files through the APIIt works.The organization folder is for every member; a workspace only for its members.
A member changes an organization folder file403 FORBIDDEN. In the app the controls are not there.Only owners and admins change the organization folder.
A member who is admin of one workspace sets a status thereIt works.In a workspace, the effective workspace role counts.
That same member sets a status in the organization folder403 FORBIDDEN.In the organization folder, the organization role counts.
Two files with the same name are in one folderBoth exist, each with its own ID.File names need not be unique.
The same bytes are uploaded to two workspacesTwo independent files. Each names the other as a duplicate to people who can open both.Files are never merged.
A file is renamed, moved, replaced, trashed and restoredIts ID is the same throughout.The ID never changes.
A file is uploaded into a public folderIt is restricted until it has a status that allows public use.Nothing is public by accident.
A workspace is deletedIts files become unreachable at once, and its public links stop. A restore within 30 days brings everything back.See Workspaces.
A member is removed from a workspaceThey can no longer open its files. Files they uploaded stay.Access comes from membership, not from having uploaded.
A credential's member loses access to a workspaceThe credential no longer reaches it.A credential never does more than its member.
A credential lists one workspace and asks for another404 NOT_FOUND.A credential reaches only the workspaces it lists.
A credential asks to make a file public403 FORBIDDEN, reason SESSION_REQUIRED.General access needs a person in a browser.
An agent and a person change the same file at the same momentOne change is applied. The other is refused with 409 STALE_LOCK_VERSION.Changes are checked against what was last read.
Someone opens the address of a file that was deleted for goodThe app shows its "not found" page.Nothing of the file is left.
A workspace or the organization folder has no statuses, or no default statusNew files there have no status. A file without a status is never public.Each workspace and the organization folder keeps its own list of statuses.
A status or field of the organization folder is set on a workspace's file, or one of another workspace422 VALIDATION_FAILED.A file only carries its own workspace's or organization folder's statuses and fields.
A workspace admin who is a plain member of the organization renames a status of the organization folder403 FORBIDDEN.The organization folder's statuses, fields and tags are managed by the organization's owners and admins.

Errors

The errors that every page of this area shares:

CodeStatusWhenWhat to do
UNAUTHENTICATED401Not signed in, or an invalid credential.Sign in or use a valid credential.
FORBIDDEN403Your role does not allow the action: for example changing the organization folder as a member, or setting a status as a member.Ask an owner or admin.
FORBIDDEN, reason INSUFFICIENT_SCOPE403The credential lacks the scope the operation needs. details.requiredScopes names it.Use a credential with the scope.
FORBIDDEN, reason SESSION_REQUIRED403A credential asks for something only a person in a browser can do.A person does it in the app.
FORBIDDEN, reason MAKES_FILES_PUBLIC403A move or a restore would make files public and the caller is not an owner or admin.Ask an owner or admin.
NOT_FOUND404The workspace, organization, folder, file, version or upload is unknown, deleted for good or out of your reach.Check the ID and the place it belongs to.
STALE_LOCK_VERSION409A file or folder changed since you read it.Read it again and repeat the change.
STALE_FILE_VERSION409A file got a newer version since the one you based a replacement on.Read the file again.
CONFLICT409The request conflicts with the current state. details.reason says how: IN_TRASH, NOT_IN_TRASH, NAME_TAKEN, CYCLE, VISIBILITY_CHANGE and others.See the page of the feature.
PAYLOAD_TOO_LARGE413A file is over the upload limit, or a ZIP over its limit.Send or ask for less.
UNSUPPORTED_MEDIA_TYPE415A file of a type that is not accepted.See Accepted types.
VALIDATION_FAILED422A value breaks a rule. details.field names it.Correct the field.
RATE_LIMITED429A credential passed its request limit.Wait for Retry-After seconds.

Each page lists the errors of its own actions. The shape of every error, and every code, is in Errors.

Limits

The limits people meet most often:

WhatValue
Size of one fileUp to 50 GiB; images, PDFs, Word, Excel and Figma files up to 2 GiB
Accepted types35 types, 42 extensions. See Accepted types.
File and folder names1 to 200 characters
Folder depth16 levels
Description, caption, alt text2,000, 500 and 1,000 characters
Tags on one file50
Versions per fileNo limit
Time in the trash30 days
A temporary download link10 minutes
One ZIP download10,000 files and 20 GiB
Page size of a listing1 to 100, default 50

Every limit is in Limits.

Questions and answers

What is the difference between a workspace and the organization folder? A workspace holds the files of one brand, client or business, and its members work in it. The organization folder holds files for the whole organization: everyone reads it, and owners and admins keep it.

Where should a file go: a workspace or the organization folder? Put a file in the organization folder when every workspace should use the same one, such as the company logo. Put it in a workspace when it belongs to that workspace's work.

How do I get to the organization folder? Click the organization's name at the top of the folder tree, or choose "Go to Organization folder" in the command palette.

Can I put files directly in the organization? Yes: the organization at the top of the folder tree is the organization folder. Files shared across the whole organization go there. Its top level also shows your workspaces as workspace folders, which hold each workspace's own files.

How do I get to another workspace's files? Click the workspace in the folder tree, or use the workspace switcher in the sidebar.

Why can't I upload to the organization folder? Only owners and admins of the organization change the organization folder. You can read and download everything in it.

Can I move a file from a workspace to the organization folder? Not by moving. An owner or admin uploads it to the organization folder.

What kinds of files can I keep here? Images, raw photos, design files, PDF, video, fonts, CSV, Word, Excel, Markdown and text, up to 50 GiB each (images, PDFs, Word, Excel and Figma files up to 2 GiB). See Accepted types.

Is there a limit on how many files I can keep? No limit on the number of files or folders is set.

Does Talewright change my files? No. A file downloads exactly as it was uploaded. Thumbnails and previews are made beside it.

Who can see my files? The people who can open the workspace, or for the organization folder every member of the organization. Nobody else, unless an owner or admin makes a file public.

Can someone outside the organization see a file? Only through a public link, and only while the file's status allows public use. See Sharing and public links.

What does the status on a file mean? It is a label for whether and how the file may be used, such as "Approved for public use" or "Internal use only". Each workspace and the organization folder has its own statuses. Owners and admins set it. See Statuses.

What happens when I replace a file? It gets a new version. The name, the status, the details and every link stay, and the earlier version is kept. See Versions and history.

What happens when I delete a file? It goes to the trash and can be restored for 30 days. See Trash and restore.

Can two people work on the same file at once? Yes. If both change the same file, the second change is refused instead of overwriting the first, and the app shows what to do.

Can I open several files at once? Yes. The app has its own tabs: "New tab" (Alt+T) opens another.

How do I find a file? Type into "Search files". It looks through names, descriptions, captions, alt text, tags and text fields of the whole workspace or organization folder. Filters narrow by type, status, field and tag.

Can an agent work with my files? Yes, through an API key or a connected app that you give scopes to. It acts for you and can never do more than you. See Credentials and scopes and MCP.

Can an agent make my files public or delete them for good? No. Both need a person in a browser. With the scope files:approve, an agent of an owner or admin can set statuses.

Is everything that happens to a file recorded? Changes are recorded in the audit trail: uploads, changes, moves, statuses, sharing, trash and deletion. See Audit trail.

Can I get all my files out? Yes. Download a folder or a selection as a ZIP, or export the whole organization. See Downloading and Export.