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
| Term | Meaning | Page |
|---|---|---|
| Access class | Which 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 token | The short-lived token (at1_..., 60 minutes) a connected app sends to the MCP server. It works at /mcp only. | Connected apps |
| Account | One person's sign-in: an email address, a password and a name. An account can belong to several organizations. | Sign-up and email verification |
| Activity | What was done with one API key or connected app: the audit events recorded during its requests, newest first. | Audit trail |
| Admin | The 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 text | A file's text alternative for people who cannot see it, up to 1,000 characters. | Fields and tags |
| API key | A secret string (ak1_...) that lets a script or agent act for one member, within chosen workspaces and scopes, until it expires. | Credentials and scopes |
| Archive | A ZIP download of chosen folders and files, prepared on request and offered at a temporary address. | Downloading |
| Audit event | One recorded change: who did what to which thing, when, where, and with which credential. Written <area>.<verb>, such as file.updated. | Audit trail |
| Audit trail | All audit events. People read the part of it that belongs to a credential, as its activity. | Audit trail |
| Bearer token | A token sent as Authorization: Bearer <token>: an API key or a connected app's access token. | The REST API |
| Browser only | Said of an operation that needs a person signed in with a browser. No credential can call it, whatever its scopes. | The REST API |
| Capability | One 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 |
| Caption | A short text shown with a file, up to 500 characters. | Fields and tags |
| Choice | One option of a select or multi-select field. | Fields and tags |
| Client ID | The web address by which an app that wants to connect identifies itself. | Connected apps |
| Client metadata document | The small document an app publishes at its client ID: its name and the addresses it may return to. | Connected apps |
| Connected app | An agent, such as Claude Code or Codex, that a member allowed in the browser to act for them through the MCP server. | Connected apps |
| Consent | The screen where a member chooses what an app may do and presses "Allow" or "Deny". | Connected apps |
| Credential | What 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 |
| Cursor | The opaque value (nextCursor) that asks for the next page of a list. | The REST API |
| Default status | The status new uploads get. At most one status is the default, and it never allows public use. | Statuses |
| Delegated operation | An API operation a credential may call when it holds the operation's scope. There are 80. | The REST API |
| Description | A longer text about a file, up to 2,000 characters. | Fields and tags |
| Digest | The fingerprint of a version's bytes, written sha256:<hex>. Two versions with the same digest have the same bytes. | Versions and history |
| Duplicate | Another live file in the organization whose current version has the same bytes. | Uploading |
| Effective role | The role that counts for a person in a workspace: the stronger of their organization role and their workspace role. | Members and roles |
| Error envelope | The JSON body every API error has: error.code, error.message, error.details and requestID. | Errors |
| Expired | Said of a key, a connected app, a link, an upload, a proposal or an export whose time ran out. | Limits |
| Export | A ZIP of an organization's files and their details, requested by an owner or admin and kept for 7 days once ready. | Export |
| Favorite | A file or folder a person starred for themselves. Favorites are private to that person. | Folders, moving and finding |
| Field | A 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 |
| File | A named item with one or more versions of bytes, plus details: folder, tags, texts, status and field values. | Overview |
| File space | Where a file lives: one workspace, or the organization folder. | Overview |
| Files & Assets | The name of the files area in the app. | Overview |
files:approve | The 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:read | The scope that lets a credential read files, folders, tags, uploads and proposals, and get temporary file addresses. | Credentials and scopes |
files:write | The scope that lets a credential upload, edit, organize, trash and restore files, and create proposals. It includes files:read. | Credentials and scopes |
| Folder | A container for files and other folders. Folders nest up to 16 deep. | Folders, moving and finding |
| Folder path | The folders from the top level down to a file's folder. | Folders, moving and finding |
| Gallery | The public page of a public folder, listing its subfolders and public files. | Sharing and public links |
| General access | Who 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 approval | The reason applying a library proposal is browser only: a person reviews what an agent prepared. | The REST API |
| Image variant | A 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 |
| Invitation | An emailed link that lets an address join an organization with a role and workspaces. It works for 7 days. | Invitations |
| Key management | The organization settings page where owners and admins see and revoke every member's API keys and connected apps. | Credentials and scopes |
| Last client | The MCP client that last connected with a credential: its name, version and protocol version. | Credentials and scopes |
| Last used | When a credential last made a request, refreshed at most once a minute. | Credentials and scopes |
| Library | The 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 proposal | The 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 |
| Live | Said of a file, folder, workspace or organization that is not in the trash and not deleted. | Trash and restore |
| Lock version | A 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 |
| MCP | Model Context Protocol: the way AI agents call tools in other products. Talewright's MCP server offers its file operations as tools. | MCP |
| Member | The 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 |
| OAuth | The standard sign-in flow by which an app gets permission in the browser instead of a pasted key. Connected apps use it. | Connected apps |
| Organization | The top level: a company or team with its members, workspaces and organization folder. Every credential belongs to one organization. | Organizations |
| Organization folder | The 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 |
| Overlap | The time (0 to 24 hours) the old secret of a rotated key keeps working. | Credentials and scopes |
| Owner | The 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 |
| Playback | The MP4 rendition of a video that browsers can play, made when the original cannot be played as it is. | Downloading |
| Prefix | The visible start of an API key, ak1_<public ID>. It identifies the key in lists and is not a secret. | Credentials and scopes |
| Preview | A WebP rendering of a file's current version that fits 1,600 pixels. | Downloading |
| Public | Said 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 link | The stable address of a public file. It always serves the file's current version. | Sharing and public links |
| Public operation | An API operation that needs no sign-in, such as sign-in itself or reading the contract. There are 12. | The REST API |
| Purge | To delete for good. A purged file, folder, workspace or organization cannot be restored. | Trash and restore |
purgeAfter | The time after which a trashed or deleted thing is purged. | Trash and restore |
| Rate limit | A cap on how many times something may be tried in a time window. Past it the API answers 429 RATE_LIMITED. | Limits |
| Refresh token | The token (rt1_...) a connected app uses to get a new access token. Each works once. | Connected apps |
| Reject reason | Why 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 |
| Resource | In MCP, something an agent can read by address. Talewright offers seven resource templates, such as a file or a proposal. | MCP |
| Restricted | General access limited to people with access to the file's workspace or organization folder. The opposite of public. | Sharing and public links |
| Revoke | To end a credential at once. A revoked key or connected app answers 401 and cannot be brought back. | Credentials and scopes |
| Role | What a person may do: owner, admin or member, in an organization and optionally in a single workspace. | Members and roles |
| Rotate | To give an API key a new secret while keeping its prefix, scopes, workspaces and expiry. | Credentials and scopes |
| Scope | One permission of a credential. There are four: workspace:read, files:read, files:write and files:approve. | Credentials and scopes |
| Security email | An 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 |
| Session | A signed-in browser. It lasts 30 days and can be ended from the session list. | Sign-in and sessions |
| Session operation | An 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 URL | A temporary address that serves one version's bytes, thumbnail, preview or playback for 10 minutes to whoever holds it. | Downloading |
| Sole owner | The 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 |
| Stale | Said 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 |
| Status | A 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 |
| Suggestion | The app's word for a library proposal. | The organization folder and suggestions |
| Tag | A 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 |
| Thumbnail | A WebP rendering of a file's current version that fits 320 pixels (thumb). | Downloading |
| Tool | In MCP, one action an agent can call. Each Talewright tool is one API operation; there are 63. | MCP |
| Trash | Where removed files and folders wait for 30 days. Until then they can be restored. | Trash and restore |
| Upload | The act and the record of bringing a file's bytes in: started, sent, completed, verified, then ready or rejected. | Uploading |
| Variant | Which rendering of a version a signed URL serves: original, thumb, preview or playback. | Downloading |
| Verified email | An 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 |
| Version | One immutable set of bytes of a file. Replacing a file adds a version; the newest is the current version. | Versions and history |
| Visibility | The API's name for general access: restricted or public. | Sharing and public links |
| Workspace | One brand, client or business inside an organization, with its own members and files. | Workspaces |
workspace:read | The 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: publicare not the same.visibilityis the file's own setting. A file is public only when it is also live and its status allows public use. A trashed file keepsvisibility: publicbut 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.
requestIDhas 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'sopen.