Talewright Docs Open the app

Glossary

Summary

Every term Talewright uses, in the app, in the API and in these pages, defined in one or two sentences, with the page that explains it in full. Terms are in alphabetical order. Words in code style are the exact spelling the API uses.

Terms

TermMeaningPage
Access classWhich kind of caller an API operation accepts: public (anyone), session (only a person signed in with a browser) or delegated (a session, or a credential with the operation's scope).The REST API
Access tokenThe short-lived token (at1_..., 60 minutes) a connected app sends to the MCP server. It works at /mcp only.Connected apps
AccountOne person's sign-in: an email address, a password and a name. An account can belong to several organizations.Sign-up and email verification
ActivityWhat was done with one API key or connected app: the audit events recorded during its requests, newest first.Audit trail
AdminThe middle role. An admin manages the organization, its workspaces, members and files, but cannot grant or remove the owner role, or delete or restore the organization.Members and roles
Alt textA file's text alternative for people who cannot see it, up to 1,000 characters.Fields and tags
API keyA secret string (ak1_...) that lets a script or agent act for one member, within chosen workspaces and scopes, until it expires.Credentials and scopes
ArchiveA ZIP download of chosen folders and files, prepared on request and offered at a temporary address.Downloading
Audit eventOne recorded change: who did what to which thing, when, where, and with which credential. Written <area>.<verb>, such as file.updated.Audit trail
Audit trailAll audit events. People read the part of it that belongs to a credential, as its activity.Audit trail
Bearer tokenA token sent as Authorization: Bearer <token>: an API key or a connected app's access token.The REST API
Browser onlySaid of an operation that needs a person signed in with a browser. No credential can call it, whatever its scopes.The REST API
CapabilityOne action of the product, with a unique ID such as workspace.files.search. Each API operation is one capability, and an MCP tool is named after it.Roles and permissions
CaptionA short text shown with a file, up to 500 characters.Fields and tags
ChoiceOne option of a select or multi-select field.Fields and tags
Client IDThe web address by which an app that wants to connect identifies itself.Connected apps
Client metadata documentThe small document an app publishes at its client ID: its name and the addresses it may return to.Connected apps
Connected appAn agent, such as Claude Code or Codex, that a member allowed in the browser to act for them through the MCP server.Connected apps
ConsentThe screen where a member chooses what an app may do and presses "Allow" or "Deny".Connected apps
CredentialWhat a script or agent presents instead of a person's session: an API key or a connected app. It acts for one member in one organization.Credentials and scopes
CursorThe opaque value (nextCursor) that asks for the next page of a list.The REST API
Default statusThe status new uploads get. At most one status is the default, and it never allows public use.Statuses
Delegated operationAn API operation a credential may call when it holds the operation's scope. There are 80.The REST API
DescriptionA longer text about a file, up to 2,000 characters.Fields and tags
DigestThe fingerprint of a version's bytes, written sha256:<hex>. Two versions with the same digest have the same bytes.Versions and history
DuplicateAnother live file in the organization whose current version has the same bytes.Uploading
Effective roleThe role that counts for a person in a workspace: the stronger of their organization role and their workspace role.Members and roles
Error envelopeThe JSON body every API error has: error.code, error.message, error.details and requestID.Errors
ExpiredSaid of a key, a connected app, a link, an upload, a proposal or an export whose time ran out.Limits
ExportA ZIP of an organization's files and their details, requested by an owner or admin and kept for 7 days once ready.Export
FavoriteA file or folder a person starred for themselves. Favorites are private to that person.Folders, moving and finding
FieldA piece of information the files of one workspace or the organization folder can carry, defined by that place's owners and admins: text, number, date, select or multi-select. Each workspace and the organization folder have their own fields. Status is the built-in first field.Fields and tags
FileA named item with one or more versions of bytes, plus details: folder, tags, texts, status and field values.Overview
File spaceWhere a file lives: one workspace, or the organization folder.Overview
Files & AssetsThe name of the files area in the app.Overview
files:approveThe scope that lets a credential set file statuses, and confirm moves that make files public. No write scope includes it; only owners and admins can grant it.Credentials and scopes
files:readThe scope that lets a credential read files, folders, tags, uploads and proposals, and get temporary file addresses.Credentials and scopes
files:writeThe scope that lets a credential upload, edit, organize, trash and restore files, and create proposals. It includes files:read.Credentials and scopes
FolderA container for files and other folders. Folders nest up to 16 deep.Folders, moving and finding
Folder pathThe folders from the top level down to a file's folder.Folders, moving and finding
GalleryThe public page of a public folder, listing its subfolders and public files.Sharing and public links
General accessWho can open a file or folder: "Restricted" (people with access to its workspace or organization folder) or "Anyone with the link" (public).Sharing and public links
Human approvalThe reason applying a library proposal is browser only: a person reviews what an agent prepared.The REST API
Image variantA resized and re-encoded copy of an image, made when it is first asked for by putting /_img/{options} in front of the path of a signed link or a public link.Image delivery
InvitationAn emailed link that lets an address join an organization with a role and workspaces. It works for 7 days.Invitations
Key managementThe organization settings page where owners and admins see and revoke every member's API keys and connected apps.Credentials and scopes
Last clientThe MCP client that last connected with a credential: its name, version and protocol version.Credentials and scopes
Last usedWhen a credential last made a request, refreshed at most once a minute.Credentials and scopes
LibraryThe API's name for the organization folder: its paths (/v1/organizations/{organizationID}/library/...), capability IDs (library.*), MCP tools (library_*) and web addresses (/w/{workspaceID}/files/library). See Organization folder.The organization folder and suggestions
Library proposalThe API's name for a batch of suggested changes to files (tags, moves, names, alt text) that a person reviews and applies, in a workspace or the organization folder. Called a suggestion in the app.The organization folder and suggestions
LiveSaid of a file, folder, workspace or organization that is not in the trash and not deleted.Trash and restore
Lock versionA number on every file and folder (lockVersion) that moves with each change to its details. A change must send the value it was based on, so it cannot overwrite someone else's change unseen.The REST API
MCPModel Context Protocol: the way AI agents call tools in other products. Talewright's MCP server offers its file operations as tools.MCP
MemberThe basic role, and also any person who belongs to an organization. A member reads and changes files in the workspaces they were added to and reads the organization folder.Members and roles
OAuthThe standard sign-in flow by which an app gets permission in the browser instead of a pasted key. Connected apps use it.Connected apps
OrganizationThe top level: a company or team with its members, workspaces and organization folder. Every credential belongs to one organization.Organizations
Organization folderThe organization's shared file space that every workspace sees. Every member reads it; owners and admins change it. The API, capability IDs, MCP tools and web addresses call it the library.The organization folder and suggestions
OverlapThe time (0 to 24 hours) the old secret of a rotated key keeps working.Credentials and scopes
OwnerThe strongest role. Only owners grant or remove the owner role and delete or restore the organization. A live organization always has at least one.Members and roles
PlaybackThe MP4 rendition of a video that browsers can play, made when the original cannot be played as it is.Downloading
PrefixThe visible start of an API key, ak1_<public ID>. It identifies the key in lists and is not a secret.Credentials and scopes
PreviewA WebP rendering of a file's current version that fits 1,600 pixels.Downloading
PublicSaid of a file anyone with the link can open now: it is live, its status allows public use, and it or a folder above it has general access "Anyone with the link".Sharing and public links
Public linkThe stable address of a public file. It always serves the file's current version.Sharing and public links
Public operationAn API operation that needs no sign-in, such as sign-in itself or reading the contract. There are 12.The REST API
PurgeTo delete for good. A purged file, folder, workspace or organization cannot be restored.Trash and restore
purgeAfterThe time after which a trashed or deleted thing is purged.Trash and restore
Rate limitA cap on how many times something may be tried in a time window. Past it the API answers 429 RATE_LIMITED.Limits
Refresh tokenThe token (rt1_...) a connected app uses to get a new access token. Each works once.Connected apps
Reject reasonWhy an upload was refused after verification, such as TYPE_MISMATCH or MALWARE.Errors
requestID (in a create)An ID you choose and send with a create, so that repeating the request cannot create a second thing.The REST API
requestID (in an error)The ID of the request that failed, the same as the x-request-id response header. Quote it when asking for help.The REST API
ResourceIn MCP, something an agent can read by address. Talewright offers seven resource templates, such as a file or a proposal.MCP
RestrictedGeneral access limited to people with access to the file's workspace or organization folder. The opposite of public.Sharing and public links
RevokeTo end a credential at once. A revoked key or connected app answers 401 and cannot be brought back.Credentials and scopes
RoleWhat a person may do: owner, admin or member, in an organization and optionally in a single workspace.Members and roles
RotateTo give an API key a new secret while keeping its prefix, scopes, workspaces and expiry.Credentials and scopes
ScopeOne permission of a credential. There are four: workspace:read, files:read, files:write and files:approve.Credentials and scopes
Security emailAn email about your account's safety that cannot be turned off, such as the one announcing a new API key or connected app.Credentials and scopes
SessionA signed-in browser. It lasts 30 days and can be ended from the session list.Sign-in and sessions
Session operationAn API operation only a browser session may call. There are 66, in four groups: credential control, access control, permanent deletion and human approval.The REST API
Signed URLA temporary address that serves one version's bytes, thumbnail, preview or playback for 10 minutes to whoever holds it.Downloading
Sole ownerThe only owner of a live organization. A sole owner cannot leave, be removed, be demoted or delete their account until someone else is an owner or the organization is deleted.Members and roles
StaleSaid of a proposal item whose file changed after the proposal was made, or whose proposal expired. A stale item changes nothing.The organization folder and suggestions
StatusA label on a file from its workspace's or the organization folder's own list, such as "Approved for public use" or "Internal use only". Only a status that allows public use lets a file be public.Statuses
SuggestionThe app's word for a library proposal.The organization folder and suggestions
TagA short label on files, up to 50 characters, lower case. A tag is created by naming it on a file and belongs to one workspace or the organization folder; its owners and admins rename and delete it.Fields and tags
ThumbnailA WebP rendering of a file's current version that fits 320 pixels (thumb).Downloading
ToolIn MCP, one action an agent can call. Each Talewright tool is one API operation; there are 63.MCP
TrashWhere removed files and folders wait for 30 days. Until then they can be restored.Trash and restore
UploadThe act and the record of bringing a file's bytes in: started, sent, completed, verified, then ready or rejected.Uploading
VariantWhich rendering of a version a signed URL serves: original, thumb, preview or playback.Downloading
Verified emailAn email address whose owner opened the verification link. Needed to delete an account, an organization or a workspace, and to set statuses through a credential.Sign-up and email verification
VersionOne immutable set of bytes of a file. Replacing a file adds a version; the newest is the current version.Versions and history
VisibilityThe API's name for general access: restricted or public.Sharing and public links
WorkspaceOne brand, client or business inside an organization, with its own members and files.Workspaces
workspace:readThe scope that lets a credential read the organization, its workspaces and their members.Credentials and scopes

Words that are easy to mix up

  • Member is both a role and the general word for anyone in an organization. "Owners and admins" always means the two stronger roles.
  • Public and visibility: public are not the same. visibility is the file's own setting. A file is public only when it is also live and its status allows public use. A trashed file keeps visibility: public but is not public.
  • Trash and purge. Trashing can be undone for 30 days. Purging cannot be undone.
  • Delete for organizations and workspaces works like the trash: they stay restorable for 30 days, then they are purged.
  • Organization folder and library proposal. The organization folder (the API's library) is a file space. A library proposal is a batch of suggested changes, and exists in workspaces as well as in the organization folder.
  • requestID has two meanings: the ID you choose for a safe retry of a create, and the ID of a request in an error body.
  • Token invalid (TOKEN_INVALID) is about emailed links. Invalid token (INVALID_TOKEN) is about API keys and access tokens.
  • Revoke, disconnect and expire all end a credential. Revoking and disconnecting are done by someone; expiring happens by itself.
  • Credential, API key and connected app. Both an API key and a connected app are credentials. The app's settings page for API keys is titled "Credentials".
  • Status and state. A status is a label people put on a file. A state is where something is in its life: an upload's pending, a proposal's open.