Talewright Docs Open the app

The REST API

Summary

Everything Talewright does goes through one REST API under /v1. The web app uses it, the MCP server runs the same operations, and scripts and agents call it directly with an API key. This page describes what every operation has in common: the address, signing in, the error shape, paging, protection against overwriting other people's changes, safe retries, rate limits, and which operations a script may call at all.

The API is described by an OpenAPI contract that the service publishes itself. The contract is the precise reference for each operation's inputs and outputs. This page tells you how to read it.

  • Base URL: https://app.usetalewright.com
  • Contract: https://app.usetalewright.com/v1/openapi.json
  • Operations: 172. A credential can call 82 of them.

Who can do what

ActionOwnerAdminMemberSigned-in personCredentialScope a credential needs
Read the OpenAPI contractYes, and anyone without signing inYesNone
Call a public operation (12)Yes, and anyone without signing inIgnoredNone
Call a browser-only operation (78)By roleBy roleBy roleYesNoBrowser only
Call a delegated operation (82)By roleBy roleBy roleYesYesThe operation's scope
  • What each role may do, operation by operation, is in Roles and permissions.
  • A credential acts as its member, so the role columns apply to it too.

How it works

Addresses

  • Every operation is at https://app.usetalewright.com/v1/....
  • The version is in the path. All of today's operations are version 1.
  • Use https.
  • File bytes are not served from this host. Temporary and public file addresses point at https://files.talewrightusercontent.com. See Downloading.
  • Two service endpoints sit outside /v1: GET /healthz (the service runs) and GET /readyz (the service is ready). Both need no sign-in.
  • The MCP endpoint (/mcp) and the OAuth endpoints (/oauth/...) are on the same host but are not part of the REST API. See MCP and Connected apps.

Requests and responses

  • Bodies are JSON. Send Content-Type: application/json with a body.
  • Property names are camelCase. A property that holds an ID ends in ID: workspaceID, folderID, fileIDs.
  • IDs are UUID strings.
  • Times are RFC 3339 strings in UTC, such as 2026-11-14T09:12:44Z.
  • A request body may be up to 3 MiB.
  • A request has 30 seconds. After that the answer is 503 TIMEOUT.
  • Text you send must not contain control characters. Names are trimmed. Descriptions, captions and text field values may hold line breaks and tabs. Alt text may not.
  • A tag holds no comma. One that does answers 422 VALIDATION_FAILED with the message "a tag cannot contain a comma": on tags when it is set on a file or named in an add_tag or remove_tag item of a suggestion, on name when a tag is renamed.
  • A success answers 200, 201 (created), 202 (accepted, work continues in the background) or 204 (done, no body).

Workspace paths and library paths

Files live in a workspace or in the organization folder (the API's library). The two have the same operations under two path prefixes:

Files ofPath prefix
One workspace/v1/workspaces/{workspaceID}/...
The organization folder/v1/organizations/{organizationID}/library/...

For example GET /v1/workspaces/{workspaceID}/files and GET /v1/organizations/{organizationID}/library/files take the same query parameters and answer the same shape.

Signing in with a browser session

  • POST /v1/auth/sign-in with email and password answers 204 and sets the session cookie __Host-session.
  • The cookie is the session. It lasts 30 days.
  • The cookie is for the web app. It is not readable by scripts in the page.
  • A browser session can call every operation its person's role allows.
  • GET /v1/auth/session tells whether the browser is signed in, without treating a signed-out visit as an error: it answers 200 with me: null.
  • GET /v1/me answers the signed-in person and the workspaces they reach.
  • Requests that change something (POST, PUT, PATCH, DELETE) are checked for where they come from:
    • A request that sends an Origin header must name the app's own origin, https://app.usetalewright.com. Any other origin is refused with 403 FORBIDDEN, with or without a session.
    • A request that carries the session cookie must send that Origin header.
  • This means a session works from the Talewright web app and from nowhere else. Other programs use an API key.

Signing in with an API key

  • Send Authorization: Bearer ak1_... on every request. See Credentials and scopes.
  • Send no cookie.
  • Send no Origin header. A script that sends a foreign Origin on a changing request is refused with 403 FORBIDDEN.
  • The key works for the 82 delegated operations, within its scopes and workspaces.
  • A connected app's access token (at1_...) does not work here. It answers 401 UNAUTHENTICATED with reason INVALID_TOKEN. Connected apps use MCP.

How a request with a bearer token is checked

In this order. The first check that fails decides the answer.

StepCheckRefusal
1A session cookie was sent too.401 UNAUTHENTICATED, reason AMBIGUOUS_CREDENTIALS
2The client address has used up its failed authentications.429 RATE_LIMITED
3The token is invalid, expired or revoked, is not a Bearer token, or is an OAuth token.401 UNAUTHENTICATED, reason INVALID_TOKEN, with WWW-Authenticate: Bearer error="invalid_token"
4The operation is browser only.403 FORBIDDEN, reason SESSION_REQUIRED, or HUMAN_APPROVAL_REQUIRED for applying a proposal
5The credential lacks the operation's scope.403 FORBIDDEN, reason INSUFFICIENT_SCOPE, with details.requiredScopes and WWW-Authenticate: Bearer error="insufficient_scope", scope="..."
6The credential or its organization is over its request rate.429 RATE_LIMITED with Retry-After
7The workspace or organization in the path is outside the credential, or the member no longer reaches it.404 NOT_FOUND
8The member's role does not allow the action.403 FORBIDDEN
9The input is not valid.422 VALIDATION_FAILED
  • A public operation ignores the Authorization header, whatever it holds: nothing is authenticated and nothing is counted. One exception: a bearer token sent together with a session cookie is still refused at step 1.
  • On every other operation a token that does not authenticate answers 401 and counts as a failed authentication of the client address.
  • Because step 3 comes before step 4, only a valid credential learns that an operation is browser only.

Access classes

Every operation belongs to one of three access classes. The contract states the class of each operation.

ClassCountWho may call it
public12Anyone, without signing in. Sign-up, sign-in, the emailed-link steps, the invitation preview, the contract and the two service endpoints.
session78Only a person signed in with a browser. No credential, whatever its scopes.
delegated82A browser session, or a credential that holds the operation's scope.

A session operation names the reason it is browser only:

ReasonCountWhat it coversA bearer token gets
CREDENTIAL_CONTROL22Signing out, your account and sessions, sending feedback, API keys, connected apps, consent to an app, and an organization's oversight of credentials.SESSION_REQUIRED
ACCESS_CONTROL48Organizations, workspaces, members, invitations, the statuses and fields of each workspace and the organization folder, general access of files and folders, exports, leaving, deleting and restoring.SESSION_REQUIRED
PERMANENT_DELETE6Deleting a trashed file or folder for good, and emptying the trash.SESSION_REQUIRED
HUMAN_APPROVAL2Applying a library proposal.HUMAN_APPROVAL_REQUIRED

A delegated operation names one scope: workspace:read, files:read, files:write, files:approve, or any for the two operations every live credential may call.

What "needs a person in a browser" means

It means the operation is in the session class. In practice:

  • The request must carry the session cookie of someone who signed in with their email and password.
  • The request must come from the Talewright web app.
  • No API key and no connected app can call it, even one that holds all four scopes and acts for an owner.
  • The reason is always one of the four above: the operation controls credentials, controls who can access what, deletes for good, or is the step where a person reviews what an agent prepared.

The product draws the line there on purpose. An agent can prepare work, do reversible work and, with an explicit scope, set statuses. It cannot give itself more access, open files to the public, or destroy anything for good.

Tenancy

  • Every ID is checked against what the caller reaches.
  • An ID that is unknown, malformed, in another organization, in a workspace the caller does not reach, or outside a credential's workspaces answers the same 404 NOT_FOUND.
  • This holds for IDs in paths, in query parameters, in bodies and in cursors.
  • Refusals come in a fixed order: 404, then 403, then 422.

Errors

Every error has the same body:

{
  "error": {
    "code": "STALE_LOCK_VERSION",
    "message": "This changed since you opened it",
    "details": { "currentLockVersion": 5 }
  },
  "requestID": "0192f0d4-9c61-7355-bea0-7ebc5b6d2a45"
}
  • Branch on error.code and error.details.reason. Never on message.
  • details is always present, as an object or null.
  • There are 20 codes. All of them, with every reason, are in Errors.

Paging

  • Lists take two query parameters: limit (1 to 100, default 50) and cursor.
  • A list answers { "items": [...], "nextCursor": "..." }.
  • nextCursor is null on the last page. Otherwise pass it as cursor to get the next page, with the same other parameters.
  • A cursor is opaque. Do not build or change one.
  • A cursor belongs to the list it came from. Used on another workspace's list, it never returns the first workspace's items.
  • The order of a list is stable, so paging neither skips nor repeats items that did not change.
  • An invalid cursor or limit answers 422 VALIDATION_FAILED on that parameter.
  • There is no page number, and no total count, with two exceptions. A list of library proposals also answers totalCount, the number of proposals in the state asked for over all pages. A list of duplicate groups also answers totalCount and hiddenCount: the groups the caller has not hidden, and those they have.
  • A few short lists are not paged and answer only items: the workspaces a credential reaches, the statuses, the status counts of one place, the fields, favorites and deleted workspaces.
  • Each workspace and the organization folder have their own status list and field list. In the status list, fileCount, publicFileCount and noStatusFileCount count the live files of that workspace or the organization folder, the same for everyone who reads it. The fileCount of every field and choice in the field list counts the same way. See Statuses.
  • In the field list, every field and choice reads trashedFileCount: the files in that workspace's or the organization folder's trash that have a value for the field, or that choice. Deleting the field or the choice clears the value on those files too. It is a number only for an owner or admin of that workspace or the organization folder in a browser session. For every credential it is null. See Fields and tags.
  • In the status list, every status reads trashedFileCount the same way: the files in that workspace's or the organization folder's trash that have the status, which a deletion of the status also leaves without one. For every credential it is null.

Lock versions

Two people, or a person and an agent, can open the same file and change it. Lock versions stop the second change from silently overwriting the first.

  • Every file and every folder has a lockVersion, a whole number.
  • A change to a file or folder must send the lockVersion it was based on as expectedLockVersion. In a PATCH it is a body property. In a DELETE (move to trash) it is a query parameter.
  • If expectedLockVersion equals the current lockVersion, the change is applied and the answer carries the new lockVersion.
  • If it does not, nothing changes and the answer is 409 STALE_LOCK_VERSION with details.currentLockVersion.
  • On STALE_LOCK_VERSION: read the file or folder again, apply your change to what you now see, and send it with the new value.
  • A file's lockVersion moves when its details change (name, folder, tags, alt text, description, caption, field values), when it is trashed or restored, when one of its tags is renamed or deleted, and when a field or choice it had is deleted.
  • A file's lockVersion does not move when the file gets a new version.
  • Leaving out expectedLockVersion answers 422 VALIDATION_FAILED.

Two related checks work the same way:

  • Replacing a file's bytes. An upload that replaces a file names the version it is based on as baseVersionID. If the file got a newer version meanwhile, the answer is 409 STALE_FILE_VERSION with details.currentVersionID.
  • Library proposals. Each item remembers the lockVersion of its file (baseLockVersion). When a person applies the item and the file changed since, the item becomes stale and changes nothing.

Operations on many files at once (setting a status or a field on up to 100 files) take no lock version. They set one value and are safe to repeat.

Previewing a change with dryRun

  • One operation takes dryRun: setting a status on files (POST .../files/status), in a workspace and in the organization folder.
  • With "dryRun": true the request changes nothing. It answers 200 with what it would do right now: changedFileIDs, madePublicFileIDs and restrictedFileIDs, and "dryRun": true.
  • A preview is checked like the change: the same scope (files:approve), the same role and the same refusals. It writes nothing to the audit trail.
  • A preview needs no confirmVisibilityChange and is never refused with VISIBILITY_CHANGE.
  • Use it to show a person the whole effect of a change that takes several requests before any of them is made. See Previewing a status change.

Safe retries with requestID

A network failure can hide whether a create went through. requestID makes repeating it safe.

  • Six creates take a requestID property in the body: creating a folder, starting an upload and creating a library proposal, each in a workspace and in the organization folder.
  • You choose it: 1 to 64 letters, digits, - or _. Anything else answers 422 VALIDATION_FAILED on requestID.
  • Over REST it is optional. Over MCP it is required.
  • Repeating the same request with the same requestID within 24 hours does not create a second thing. It answers 201 with what the first request created, as it is now.
  • This also holds when two copies of the request arrive at the same time: one thing is created.
  • The same requestID with a different body, or in another workspace, answers 409 CONFLICT with reason REQUEST_REUSED.
  • A requestID is yours. Another member using the same string is not affected by it.
  • A requestID is remembered only when the create went through. A create that was refused, for example with 422 VALIDATION_FAILED, remembers nothing: the same requestID can be sent again, with the same body or a corrected one.
  • A workspace and the organization folder keep their request IDs apart, for each of the three creates. A requestID used for a folder, an upload or a proposal in a workspace makes a new one when it is sent for the same create in the organization folder.
  • A repeated proposal create answers with the first proposal even when one of its files was trashed since. The repeat is matched to the first request before its files are looked at. See The organization folder and suggestions.
  • After 24 hours a requestID is forgotten and counts as new.

Other changes need no requestID:

Kind of changeWhy a repeat is safe
Changes with expectedLockVersionA repeat of a change that went through answers STALE_LOCK_VERSION.
Replacements with baseVersionIDA repeat answers STALE_FILE_VERSION.
PUT operations (reordering, general access)They set a state; setting it twice changes nothing more.
Setting a status or a field on filesThe same value again changes nothing more.
Completing an uploadCompleting again returns the upload unchanged.

Request IDs for tracing

This is a different thing from the requestID you put in a create.

  • Every response carries an x-request-id header.
  • Every error body carries the same value as requestID.
  • You may send your own x-request-id: up to 128 letters, digits, -, _, . or :. It is then used as is. Anything else is replaced by a generated ID.
  • Audit events recorded during the request carry the same ID.
  • Quote it when you report a problem.

Rate limiting

  • A credential may make 600 requests a minute. All credentials of one organization together may make 3,000 a minute. REST and MCP requests count together.
  • A refused request answers 429 RATE_LIMITED with two things:
    • the Retry-After header: whole seconds to wait, at least 1;
    • details.retryAfterSeconds: the same number.
  • There are no other rate limit headers. No header tells you the limit, how much is left or when the window resets, on successful responses or on refusals.
  • Windows are fixed. A window starts with the first request and lasts one minute. Refused requests do not extend it.
  • A client address that fails bearer authentication 100 times in 15 minutes is refused with 429 for the rest of that window, valid keys included.
  • Sign-in, sign-up, emailed links, invitations and key creation have their own limits. All are in Limits.
  • Requests made in a browser session are not counted against the credential and organization limits.

Answers you must not cache

  • An answer that carries a key (creating or rotating an API key) is sent with Cache-Control: no-store.
  • A temporary file address works for 10 minutes. Ask for a new one instead of keeping it.
  • While a temporary file address works, a request whose If-None-Match names the ETag it answered before gets 304 Not Modified without a body. See Downloading.

In the app

  • The API has no page of its own in the app.
  • Create an API key under Settings > Credentials. See Credentials and scopes.
  • The contract is at https://app.usetalewright.com/v1/openapi.json. The app also serves a short guide for agents at https://app.usetalewright.com/agent-guide.md.

For agents

Reading the OpenAPI contract

GET /v1/openapi.json answers the contract as an OpenAPI 3.1 document. It needs no sign-in.

Each operation in it carries, besides the standard OpenAPI parts:

PropertyMeaningExample
operationIdA name for generated clients.list_files
x-capabilityThe operation's capability ID. It is unique, it names the action everywhere in the product, and with dots replaced by underscores it is the MCP tool name.workspace.files.search
x-accessThe access class: {"class": "public"}, {"class": "session", "reason": "..."} or {"class": "delegated", "scope": "..."}.{"class": "delegated", "scope": "files:read"}
x-mcpWhether the operation is an MCP tool: none, tool or tool+resource.tool
securityThe standard OpenAPI form of the same access rule: the session cookie, and for delegated operations the apiKey bearer scheme with the scope.
responsesEvery status the operation answers, each with the codes and reasons it can carry.
  • components.securitySchemes defines session (the cookie __Host-session) and apiKey (HTTP bearer, format ak1_<public ID>_<secret>).
  • components.schemas defines every request and response body. ErrorEnvelope is the error body. ErrorCode lists the 20 codes.
  • Operations are grouped by tag: auth, account, files, organizations, credentials and operations.
  • Every operation can also answer 500 INTERNAL and 503 TIMEOUT.

List every operation a credential with files:write may call:

curl -s https://app.usetalewright.com/v1/openapi.json | jq -r '
  .paths | to_entries[] | .key as $path | .value | to_entries[]
  | select(.value["x-access"].class == "delegated")
  | select(.value["x-access"].scope | IN("any", "files:read", "files:write"))
  | "\(.key | ascii_upcase) \($path)  \(.value["x-capability"])"'

Operation families

PathsWhat
/v1/auth/...Sign-up, sign-in, sign-out, the session, emailed links
/v1/me, /v1/me/...Your account, sessions, API keys and connected apps, and sending feedback
/v1/credentialThe credential a request presents
/v1/workspacesThe workspaces you reach
/v1/organizations, /v1/organizations/{organizationID}/...Organizations, members, invitations, workspaces, exports, statuses, fields, oversight of credentials
/v1/organizations/{organizationID}/library/...The organization folder: files, folders, tags, uploads, proposals, favorites, duplicates, trash
/v1/workspaces/{workspaceID}, /v1/workspaces/{workspaceID}/members/...A workspace and its members
/v1/workspaces/{workspaceID}/...A workspace's files, folders, tags, uploads, proposals, favorites, duplicates, trash
/v1/invitations/{token}Previewing and accepting an invitation
/v1/oauth/requests/...Answering an app's request to connect
/v1/openapi.jsonThe contract

Worked example

Find out what the key reaches:

curl -s https://app.usetalewright.com/v1/workspaces \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
{
  "items": [
    {
      "id": "0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21",
      "name": "Keystone Main",
      "organizationID": "0192e7c4-0b22-7e61-9f32-5dab8b7e6f41",
      "organizationName": "Keystone"
    }
  ]
}

List files, 20 at a time:

W=https://app.usetalewright.com/v1/workspaces/0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21
curl -s "$W/files?type=image&limit=20" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
# then, while nextCursor is not null:
curl -s "$W/files?type=image&limit=20&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"

Create a folder so that a retry cannot create two:

curl -s -X POST "$W/folders" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Press kit 2026", "requestID": "press-kit-folder-1"}'

Rename a file, based on the lockVersion you read:

curl -s -X PATCH "$W/files/0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedLockVersion": 3, "name": "logo-dark-2026.svg"}'

If someone changed the file meanwhile, the answer is 409 with STALE_LOCK_VERSION and details.currentLockVersion. Read the file again and repeat with that value.

Move a file to the trash:

curl -s -X DELETE "$W/files/0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01?expectedLockVersion=4" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"

A loop that handles the common answers:

  1. Send the request.
  2. 2xx: done.
  3. 429: wait Retry-After seconds, then go to 1.
  4. 409 STALE_LOCK_VERSION: read the thing again, rebuild the change, go to 1.
  5. 503 or 500: wait briefly, go to 1 with the same body (and the same requestID for a create). Give up after a few tries.
  6. 401: the key is no longer valid. Stop.
  7. 403, 404, 422, other 409: the request is wrong for the current state. Do not repeat it unchanged.

Edge cases

  • A key and a cookie together. 401 AMBIGUOUS_CREDENTIALS, even on a public operation.
  • A key on a browser-only operation. 403 SESSION_REQUIRED, whatever the key's scopes and its member's role.
  • An invalid key on a browser-only operation. 401 INVALID_TOKEN, as on a delegated one. It counts as a failed authentication.
  • A key on a public operation. The header is ignored, valid or not. The operation answers as for anyone and nothing is counted.
  • A session on GET /v1/credential. 401 UNAUTHENTICATED. That operation describes a bearer credential and a session has none.
  • A script sends Origin: https://example.com with a POST. 403 FORBIDDEN. Leave the header out.
  • A page on another site calls the API with the visitor's cookie. 403 FORBIDDEN. The Origin is not the app's.
  • An ID with a typo. 404 NOT_FOUND, the same as a well-formed ID that does not exist.
  • A path that does not exist. 404 NOT_FOUND in the ordinary error body.
  • The wrong method on an existing path. 405 METHOD_NOT_ALLOWED.
  • A body that is not JSON, or lacks a required property. 422 VALIDATION_FAILED with details: null.
  • A body without Content-Type: application/json. 415 UNSUPPORTED_MEDIA_TYPE.
  • A body over 3 MiB. 413 PAYLOAD_TOO_LARGE.
  • limit=0 or limit=101. 422 VALIDATION_FAILED on limit.
  • A cursor from another workspace's list. It never returns that workspace's items.
  • expectedLockVersion left out of a trash request. 422 VALIDATION_FAILED.
  • A create repeated with its requestID after the thing was renamed. The answer is the thing as it is now, with its new name.
  • A create repeated with its requestID after 24 hours. A second thing is created.
  • A create whose first attempt was refused. Nothing was created. Use a new requestID for the corrected request.
  • An x-request-id with spaces. It is dropped and a generated ID is used.
  • A request that takes longer than 30 seconds. 503 TIMEOUT. The work is stopped.
  • The member behind a key is removed from the workspace in the path. 404 NOT_FOUND from the next request.
  • The organization of a key is deleted. 401 INVALID_TOKEN until it is restored.

Errors

The errors every operation shares. Each feature page lists its own.

CodeStatusMeaningWhat to do
UNAUTHENTICATED401No valid session or bearer token; reasons INVALID_TOKEN and AMBIGUOUS_CREDENTIALS.Sign in, fix the key, or send only one of cookie and key.
FORBIDDEN403The role does not allow it, the Origin is wrong, or reasons SESSION_REQUIRED, HUMAN_APPROVAL_REQUIRED, INSUFFICIENT_SCOPE, MAKES_FILES_PUBLIC.See the reason.
NOT_FOUND404Unknown or out of reach.Check the ID and what the credential reaches.
METHOD_NOT_ALLOWED405The path does not take this method.Check the contract.
VALIDATION_FAILED422The input breaks a rule; details.field names it when one input did.Fix the input.
STALE_LOCK_VERSION409The file or folder changed since you read it.Read again, retry.
STALE_FILE_VERSION409The file has a newer version.Read again, retry the replacement.
CONFLICT409The request conflicts with the current state; details.reason says how.See Errors.
PAYLOAD_TOO_LARGE413The body or a file is too large.Send less.
UNSUPPORTED_MEDIA_TYPE415The body's content type, or a file's type, is not accepted.Send JSON; check accepted file types.
RATE_LIMITED429Too many requests.Wait Retry-After.
INTERNAL500A failure on our side.Retry; report the requestID if it persists.
UNAVAILABLE503Something the request needs is unavailable; details.reason says what.Retry later.
TIMEOUT503The request ran past 30 seconds.Retry.

Limits

LimitValue
Request body3 MiB
Time for one request30 seconds
Page size (limit)1 to 100, default 50
requestID1 to 64 letters, digits, - or _
A requestID is remembered24 hours
x-request-id you sendUp to 128 letters, digits, -, _, . or :
Requests per credential600 a minute
Requests per organization, all its credentials3,000 a minute
Failed bearer authentications per client address100 in 15 minutes
Files in one status or field request1 to 100
Session lifetime30 days

Questions and answers

What is the base URL? https://app.usetalewright.com. Every operation is under /v1.

Where is the API reference? The OpenAPI contract at /v1/openapi.json is the reference. It lists every operation, every input, every output and every error.

How do I authenticate a script? With an API key in the Authorization: Bearer header. Create it under Settings > Credentials.

Can I use my email and password from a script? No. Sign-in creates a browser session, and session requests are accepted only from the Talewright web app. Use an API key.

Can I use a connected app's token against REST? No. Those tokens work at /mcp only.

Which operations can a script call? The 82 in the delegated access class, within the key's scopes. In the contract they are the operations whose x-access.class is delegated.

How do I know which scope an operation needs? Read x-access.scope on the operation in the contract. A refusal also names it in details.requiredScopes.

Why can a script not make a file public or delete it for good? Those operations are browser only, by design. See What "needs a person in a browser" means.

Is there a header that shows my remaining rate limit? No. The API sends Retry-After on a 429 and nothing else.

How do I page through a long list? Pass each answer's nextCursor as cursor until it is null.

Can I get a total count of files? No list of files answers a total. Page through, or read the counts that other operations give, such as a folder's fileCount or a status's fileCount. Only a list of library proposals answers a totalCount.

Can I jump to page 7? No. Paging is by cursor only.

What is the difference between requestID in a body and x-request-id? requestID in a create's body is your key for a safe retry. x-request-id is a tracing ID that every response carries and every error body repeats as requestID.

Do I need requestID on every write? No. Only six creates take it. Changes use expectedLockVersion instead.

What happens if two agents rename the same file at once? One wins. The other gets 409 STALE_LOCK_VERSION and must read the file again.

Why did my change answer 404 and not 403? The workspace or file is outside what you reach. The API does not reveal whether it exists.

Does the API support webhooks or push notifications? No operation for them exists in the contract. Poll with the read operations.

Is there an SDK? The contract is a standard OpenAPI 3.1 document; client generators work with it. Talewright's own web app uses a client generated from it.

Is the API the same thing the web app uses? Yes. The web app calls the same /v1 operations.

How do I report a problem with a request? Send the requestID from the error body, or the x-request-id response header.