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
| Action | Owner | Admin | Member | Signed-in person | Credential | Scope a credential needs |
|---|---|---|---|---|---|---|
| Read the OpenAPI contract | Yes, and anyone without signing in | Yes | None | |||
| Call a public operation (12) | Yes, and anyone without signing in | Ignored | None | |||
| Call a browser-only operation (78) | By role | By role | By role | Yes | No | Browser only |
| Call a delegated operation (82) | By role | By role | By role | Yes | Yes | The 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) andGET /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/jsonwith 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_FAILEDwith the message "a tag cannot contain a comma": ontagswhen it is set on a file or named in anadd_tagorremove_tagitem of a suggestion, onnamewhen a tag is renamed. - A success answers
200,201(created),202(accepted, work continues in the background) or204(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 of | Path 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-inwithemailandpasswordanswers204and 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/sessiontells whether the browser is signed in, without treating a signed-out visit as an error: it answers200withme: null.GET /v1/meanswers 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
Originheader must name the app's own origin,https://app.usetalewright.com. Any other origin is refused with403 FORBIDDEN, with or without a session. - A request that carries the session cookie must send that
Originheader.
- A request that sends an
- 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
Originheader. A script that sends a foreignOriginon a changing request is refused with403 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 answers401 UNAUTHENTICATEDwith reasonINVALID_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.
| Step | Check | Refusal |
|---|---|---|
| 1 | A session cookie was sent too. | 401 UNAUTHENTICATED, reason AMBIGUOUS_CREDENTIALS |
| 2 | The client address has used up its failed authentications. | 429 RATE_LIMITED |
| 3 | The 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" |
| 4 | The operation is browser only. | 403 FORBIDDEN, reason SESSION_REQUIRED, or HUMAN_APPROVAL_REQUIRED for applying a proposal |
| 5 | The credential lacks the operation's scope. | 403 FORBIDDEN, reason INSUFFICIENT_SCOPE, with details.requiredScopes and WWW-Authenticate: Bearer error="insufficient_scope", scope="..." |
| 6 | The credential or its organization is over its request rate. | 429 RATE_LIMITED with Retry-After |
| 7 | The workspace or organization in the path is outside the credential, or the member no longer reaches it. | 404 NOT_FOUND |
| 8 | The member's role does not allow the action. | 403 FORBIDDEN |
| 9 | The input is not valid. | 422 VALIDATION_FAILED |
- A public operation ignores the
Authorizationheader, 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
401and 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.
| Class | Count | Who may call it |
|---|---|---|
public | 12 | Anyone, without signing in. Sign-up, sign-in, the emailed-link steps, the invitation preview, the contract and the two service endpoints. |
session | 78 | Only a person signed in with a browser. No credential, whatever its scopes. |
delegated | 82 | A browser session, or a credential that holds the operation's scope. |
A session operation names the reason it is browser only:
| Reason | Count | What it covers | A bearer token gets |
|---|---|---|---|
CREDENTIAL_CONTROL | 22 | Signing 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_CONTROL | 48 | Organizations, 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_DELETE | 6 | Deleting a trashed file or folder for good, and emptying the trash. | SESSION_REQUIRED |
HUMAN_APPROVAL | 2 | Applying 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, then403, then422.
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.codeanderror.details.reason. Never onmessage. detailsis always present, as an object ornull.- 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) andcursor. - A list answers
{ "items": [...], "nextCursor": "..." }. nextCursorisnullon the last page. Otherwise pass it ascursorto 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
cursororlimitanswers422 VALIDATION_FAILEDon 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 thestateasked for over all pages. A list of duplicate groups also answerstotalCountandhiddenCount: 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,publicFileCountandnoStatusFileCountcount the live files of that workspace or the organization folder, the same for everyone who reads it. ThefileCountof 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 isnull. See Fields and tags. - In the status list, every status reads
trashedFileCountthe 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 isnull.
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
lockVersionit was based on asexpectedLockVersion. In aPATCHit is a body property. In aDELETE(move to trash) it is a query parameter. - If
expectedLockVersionequals the currentlockVersion, the change is applied and the answer carries the newlockVersion. - If it does not, nothing changes and the answer is
409 STALE_LOCK_VERSIONwithdetails.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
lockVersionmoves 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
lockVersiondoes not move when the file gets a new version. - Leaving out
expectedLockVersionanswers422 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 is409 STALE_FILE_VERSIONwithdetails.currentVersionID. - Library proposals. Each item remembers the
lockVersionof its file (baseLockVersion). When a person applies the item and the file changed since, the item becomesstaleand 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": truethe request changes nothing. It answers200with what it would do right now:changedFileIDs,madePublicFileIDsandrestrictedFileIDs, 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
confirmVisibilityChangeand is never refused withVISIBILITY_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
requestIDproperty 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 answers422 VALIDATION_FAILEDonrequestID. - Over REST it is optional. Over MCP it is required.
- Repeating the same request with the same
requestIDwithin 24 hours does not create a second thing. It answers201with 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
requestIDwith a different body, or in another workspace, answers409 CONFLICTwith reasonREQUEST_REUSED. - A
requestIDis yours. Another member using the same string is not affected by it. - A
requestIDis remembered only when the create went through. A create that was refused, for example with422 VALIDATION_FAILED, remembers nothing: the samerequestIDcan 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
requestIDused 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
requestIDis forgotten and counts as new.
Other changes need no requestID:
| Kind of change | Why a repeat is safe |
|---|---|
Changes with expectedLockVersion | A repeat of a change that went through answers STALE_LOCK_VERSION. |
Replacements with baseVersionID | A 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 files | The same value again changes nothing more. |
| Completing an upload | Completing 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-idheader. - 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_LIMITEDwith two things:- the
Retry-Afterheader: whole seconds to wait, at least 1; details.retryAfterSeconds: the same number.
- the
- 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
429for 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-Matchnames theETagit answered before gets304 Not Modifiedwithout 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 athttps://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:
| Property | Meaning | Example |
|---|---|---|
operationId | A name for generated clients. | list_files |
x-capability | The 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-access | The access class: {"class": "public"}, {"class": "session", "reason": "..."} or {"class": "delegated", "scope": "..."}. | {"class": "delegated", "scope": "files:read"} |
x-mcp | Whether the operation is an MCP tool: none, tool or tool+resource. | tool |
security | The standard OpenAPI form of the same access rule: the session cookie, and for delegated operations the apiKey bearer scheme with the scope. | |
responses | Every status the operation answers, each with the codes and reasons it can carry. |
components.securitySchemesdefinessession(the cookie__Host-session) andapiKey(HTTP bearer, formatak1_<public ID>_<secret>).components.schemasdefines every request and response body.ErrorEnvelopeis the error body.ErrorCodelists the 20 codes.- Operations are grouped by tag:
auth,account,files,organizations,credentialsandoperations. - Every operation can also answer
500 INTERNALand503 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
| Paths | What |
|---|---|
/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/credential | The credential a request presents |
/v1/workspaces | The 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.json | The 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:
- Send the request.
2xx: done.429: waitRetry-Afterseconds, then go to 1.409 STALE_LOCK_VERSION: read the thing again, rebuild the change, go to 1.503or500: wait briefly, go to 1 with the same body (and the samerequestIDfor a create). Give up after a few tries.401: the key is no longer valid. Stop.403,404,422, other409: 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.comwith aPOST.403 FORBIDDEN. Leave the header out. - A page on another site calls the API with the visitor's cookie.
403 FORBIDDEN. TheOriginis 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_FOUNDin 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_FAILEDwithdetails: null. - A body without
Content-Type: application/json.415 UNSUPPORTED_MEDIA_TYPE. - A body over 3 MiB.
413 PAYLOAD_TOO_LARGE. limit=0orlimit=101.422 VALIDATION_FAILEDonlimit.- A cursor from another workspace's list. It never returns that workspace's items.
expectedLockVersionleft out of a trash request.422 VALIDATION_FAILED.- A create repeated with its
requestIDafter the thing was renamed. The answer is the thing as it is now, with its new name. - A create repeated with its
requestIDafter 24 hours. A second thing is created. - A create whose first attempt was refused. Nothing was created. Use a
new
requestIDfor the corrected request. - An
x-request-idwith 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_FOUNDfrom the next request. - The organization of a key is deleted.
401 INVALID_TOKENuntil it is restored.
Errors
The errors every operation shares. Each feature page lists its own.
| Code | Status | Meaning | What to do |
|---|---|---|---|
UNAUTHENTICATED | 401 | No valid session or bearer token; reasons INVALID_TOKEN and AMBIGUOUS_CREDENTIALS. | Sign in, fix the key, or send only one of cookie and key. |
FORBIDDEN | 403 | The 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_FOUND | 404 | Unknown or out of reach. | Check the ID and what the credential reaches. |
METHOD_NOT_ALLOWED | 405 | The path does not take this method. | Check the contract. |
VALIDATION_FAILED | 422 | The input breaks a rule; details.field names it when one input did. | Fix the input. |
STALE_LOCK_VERSION | 409 | The file or folder changed since you read it. | Read again, retry. |
STALE_FILE_VERSION | 409 | The file has a newer version. | Read again, retry the replacement. |
CONFLICT | 409 | The request conflicts with the current state; details.reason says how. | See Errors. |
PAYLOAD_TOO_LARGE | 413 | The body or a file is too large. | Send less. |
UNSUPPORTED_MEDIA_TYPE | 415 | The body's content type, or a file's type, is not accepted. | Send JSON; check accepted file types. |
RATE_LIMITED | 429 | Too many requests. | Wait Retry-After. |
INTERNAL | 500 | A failure on our side. | Retry; report the requestID if it persists. |
UNAVAILABLE | 503 | Something the request needs is unavailable; details.reason says what. | Retry later. |
TIMEOUT | 503 | The request ran past 30 seconds. | Retry. |
Limits
| Limit | Value |
|---|---|
| Request body | 3 MiB |
| Time for one request | 30 seconds |
Page size (limit) | 1 to 100, default 50 |
requestID | 1 to 64 letters, digits, - or _ |
A requestID is remembered | 24 hours |
x-request-id you send | Up to 128 letters, digits, -, _, . or : |
| Requests per credential | 600 a minute |
| Requests per organization, all its credentials | 3,000 a minute |
| Failed bearer authentications per client address | 100 in 15 minutes |
| Files in one status or field request | 1 to 100 |
| Session lifetime | 30 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.