# The REST API: questions and answers

Questions about Talewright's REST API: the base URL, authentication, the
error shape, paging, lock versions, safe retries, request IDs, rate limits,
which operations need a person in a browser, the OpenAPI contract, and
uploading and downloading step by step. The rules are in
[The REST API](../agents/rest-api.md).

## The basics

### Does Talewright have an API?

Yes. 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.

More: [The REST API, Summary](../agents/rest-api.md#summary)

### What is the base URL of the Talewright API?

`https://app.usetalewright.com`. Every operation is at
`https://app.usetalewright.com/v1/...`.

More: [The REST API, Addresses](../agents/rest-api.md#addresses)

### How is the API versioned?

The version is in the path. All of today's operations are version 1,
under `/v1`.

More: [The REST API, Addresses](../agents/rest-api.md#addresses)

### Is the API the same one the Talewright web app uses?

Yes. The web app calls the same `/v1` operations, through a client
generated from the same contract.

More: [The REST API, Summary](../agents/rest-api.md#summary)

### Where is the API reference?

The OpenAPI contract at `https://app.usetalewright.com/v1/openapi.json` is
the reference. It lists every operation, every input, every output and
every error.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### Which operations can a script call?

The 82 operations in the `delegated` access class, within the key's
scopes and workspaces. The API has 172 operations in all.

More: [The REST API, Access classes](../agents/rest-api.md#access-classes)

### Is there a page for the API in the app?

No. The API has no page of its own in the app. You create an API key under
**Settings > Credentials** and read the contract at `/v1/openapi.json`.

More: [The REST API, In the app](../agents/rest-api.md#in-the-app)

### Does the API work over plain `http`?

Use `https`. Every address of the API is an `https` address.

More: [The REST API, Addresses](../agents/rest-api.md#addresses)

### Are file bytes served from the API host?

No. Temporary and public file addresses point at
`https://files.talewrightusercontent.com`.

More: [The REST API, Addresses](../agents/rest-api.md#addresses)

### What are `/healthz` and `/readyz`?

Two service endpoints outside `/v1`. `GET /healthz` says the service runs,
and `GET /readyz` says it is ready. Both need no sign-in.

More: [The REST API, Addresses](../agents/rest-api.md#addresses)

### Are the MCP endpoint and the OAuth endpoints part of the REST API?

No. `/mcp` and `/oauth/...` are on the same host but are not part of the
REST API.

More: [The REST API, Addresses](../agents/rest-api.md#addresses)

## What the API does not have

### Does Talewright have webhooks?

No. No operation for webhooks or push notifications exists in the
contract. Poll with the read operations.

More: [The REST API, Questions and answers](../agents/rest-api.md#questions-and-answers)

### Is there an official SDK or client library?

No. Talewright publishes no SDK. The contract is a standard OpenAPI 3.1
document, and client generators work with it.

More: [The REST API, Questions and answers](../agents/rest-api.md#questions-and-answers)

### Does Talewright have a GraphQL API?

No. The API is REST under `/v1`, described by an OpenAPI contract. The
same operations are also MCP tools.

More: [The REST API, Summary](../agents/rest-api.md#summary)

### Is there a sandbox or a test environment for the API?

No. Every operation is at `https://app.usetalewright.com/v1/...`, and
there is no test mode. To try things with little at stake, use an API key
that lists a single workspace and only the scopes you test.

More: [The REST API, Addresses](../agents/rest-api.md#addresses)

### Is there a general batch endpoint for many requests at once?

No. Two operations work on many files in one request: setting a status
and setting a field value, each on 1 to 100 files. A ZIP download takes
many folders and files at once.

More: [The REST API, Lock versions](../agents/rest-api.md#lock-versions)

### Does the API take an `Idempotency-Key` header?

No. Safe retries of a create use `requestID`, a property in the request
body.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### Can I call the API from JavaScript on my own website?

No. A request that changes something and sends an `Origin` other than
`https://app.usetalewright.com` is refused with `403 FORBIDDEN`, and a
browser sends that header from another site. Call the API from a server or
a script with an API key.

More: [The REST API, Signing in with a browser session](../agents/rest-api.md#signing-in-with-a-browser-session)

### Can I sign in to the API with OAuth?

No. A connected app's access token works at `/mcp` only and answers `401`
at `/v1`. The REST API takes an API key.

More: [The REST API, Signing in with an API key](../agents/rest-api.md#signing-in-with-an-api-key)

### Does the API accept XML or form bodies?

No. Bodies are JSON. A body without `Content-Type: application/json`
answers `415 UNSUPPORTED_MEDIA_TYPE`.

More: [The REST API, Requests and responses](../agents/rest-api.md#requests-and-responses)

### Can a list answer a total count or a page number?

No. Lists have no total count and no page number. Paging is by cursor
only.

More: [The REST API, Paging](../agents/rest-api.md#paging)

## Requests and responses

### What format do request and response bodies have?

JSON. Send `Content-Type: application/json` with a body.

More: [The REST API, Requests and responses](../agents/rest-api.md#requests-and-responses)

### How are properties named in the API?

In camelCase. A property that holds an ID ends in `ID`: `workspaceID`,
`folderID`, `fileIDs`.

More: [The REST API, Requests and responses](../agents/rest-api.md#requests-and-responses)

### What format do IDs have in the API?

IDs are UUID strings, such as `0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21`.

More: [The REST API, Requests and responses](../agents/rest-api.md#requests-and-responses)

### What format do dates and times have in the API?

RFC 3339 strings in UTC, such as `2026-11-14T09:12:44Z`.

More: [The REST API, Requests and responses](../agents/rest-api.md#requests-and-responses)

### Which status codes does a successful request answer?

`200`, `201` (created), `202` (accepted, work continues in the background)
or `204` (done, no body).

More: [The REST API, Requests and responses](../agents/rest-api.md#requests-and-responses)

### What does a `202` answer mean?

Accepted: the work continues in the background. Completing an upload, for
example, answers `202` with the upload, now `verifying`, while the checks
run.

More: [Uploading, Completing](../files/uploading.md#completing)

### What happens when a request takes too long?

A request has 30 seconds. After that the answer is `503 TIMEOUT`, and the
work is stopped.

More: [The REST API, Edge cases](../agents/rest-api.md#edge-cases)

### Which characters can text I send not contain?

Control characters. Descriptions, captions and text field values may hold
line breaks and tabs. Alt text may not.

More: [The REST API, Requests and responses](../agents/rest-api.md#requests-and-responses)

### Does the API trim the names I send?

Yes. Names are trimmed. A control character such as a trailing line break
is not trimmed: it is refused.

More: [The REST API, Requests and responses](../agents/rest-api.md#requests-and-responses)

### What does the API answer for the wrong method on an existing path?

`405 METHOD_NOT_ALLOWED`. Check the contract for the methods a path takes.

More: [The REST API, Edge cases](../agents/rest-api.md#edge-cases)

### What does the API answer for a body that is not valid JSON?

`422 VALIDATION_FAILED` with `details: null`. The same holds for a body
that lacks a required property.

More: [The REST API, Edge cases](../agents/rest-api.md#edge-cases)

## Workspace paths and library paths

### What is the difference between `/v1/workspaces/...` and `/v1/organizations/.../library/...`?

They are two path prefixes for the same file operations. One works on the
files of one workspace, the other on the organization folder (the API's
library).

More: [The REST API, Workspace paths and library paths](../agents/rest-api.md#workspace-paths-and-library-paths)

### Do the workspace and organization folder operations take the same parameters?

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

More: [The REST API, Workspace paths and library paths](../agents/rest-api.md#workspace-paths-and-library-paths)

### Which path families does the API have?

- `/v1/auth/...` and `/v1/me/...`: sign-in, your account, keys and apps.
- `/v1/credential` and `/v1/workspaces`: what a credential is and reaches.
- `/v1/organizations/...`: organizations, members, statuses, fields and
  the organization folder.
- `/v1/workspaces/{workspaceID}/...`: a workspace and its files.
- `/v1/invitations/{token}`, `/v1/oauth/requests/...` and
  `/v1/openapi.json`.

More: [The REST API, Operation families](../agents/rest-api.md#operation-families)

## Authentication

### How do I authenticate a request to the API?

Send an API key as `Authorization: Bearer ak1_...` on every request. Send
no cookie and no `Origin` header.

More: [The REST API, Signing in with an API key](../agents/rest-api.md#signing-in-with-an-api-key)

### 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.

More: [The REST API, Signing in with a browser session](../agents/rest-api.md#signing-in-with-a-browser-session)

### Can I copy my browser's session cookie into a script?

No. A session works from the Talewright web app and from nowhere else: a
changing request that carries the cookie must also send the app's own
`Origin`. Other programs use an API key.

More: [The REST API, Signing in with a browser session](../agents/rest-api.md#signing-in-with-a-browser-session)

### What is the session cookie called?

`__Host-session`. It is the session, it lasts 30 days, and it is not
readable by scripts in the page.

More: [The REST API, Signing in with a browser session](../agents/rest-api.md#signing-in-with-a-browser-session)

### Should my script send an `Origin` header?

No. A script that sends a foreign `Origin` on a changing request is
refused with `403 FORBIDDEN`. Leave the header out.

More: [The REST API, Signing in with an API key](../agents/rest-api.md#signing-in-with-an-api-key)

### How does the API check where a changing request comes from?

A `POST`, `PUT`, `PATCH` or `DELETE` that sends an `Origin` header must
name `https://app.usetalewright.com`. A request that carries the session
cookie must send that header.

More: [The REST API, Signing in with a browser session](../agents/rest-api.md#signing-in-with-a-browser-session)

### Can an API key call `GET /v1/me`?

No. `GET /v1/me` is browser only. A key reads what it is with
`GET /v1/credential` and what it reaches with `GET /v1/workspaces`.

More: [Credentials and scopes, Reading the presented credential](../agents/credentials.md#reading-the-presented-credential)

### In what order is a request with an API key checked?

1. A cookie sent too: `401`, `AMBIGUOUS_CREDENTIALS`.
2. Too many failed authentications from the address: `429`.
3. An invalid token: `401`, `INVALID_TOKEN`.
4. A browser-only operation: `403`, `SESSION_REQUIRED`.
5. A missing scope: `403`, `INSUFFICIENT_SCOPE`.
6. Over the request rate: `429`.
7. A workspace out of reach: `404`.
8. The member's role: `403`.
9. Invalid input: `422`.

More: [The REST API, How a request with a bearer token is checked](../agents/rest-api.md#how-a-request-with-a-bearer-token-is-checked)

### Can someone without a valid key find out which operations are browser only?

Not from the answers. The token is checked before the operation's class,
so an invalid key gets `401` everywhere, and only a valid credential
learns that an operation is browser only. The contract itself is public.

More: [The REST API, How a request with a bearer token is checked](../agents/rest-api.md#how-a-request-with-a-bearer-token-is-checked)

### Does a public operation look at my API key?

No. 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.

More: [The REST API, How a request with a bearer token is checked](../agents/rest-api.md#how-a-request-with-a-bearer-token-is-checked)

### Does a failed authentication count against me?

Yes. On every operation that is not public, a token that does not
authenticate answers `401` and counts as a failed authentication of the
client address.

More: [The REST API, How a request with a bearer token is checked](../agents/rest-api.md#how-a-request-with-a-bearer-token-is-checked)

## Access classes and browser-only operations

### What is an access class?

It says which kind of caller an operation accepts: `public`, `session` or
`delegated`. The contract states the class of each operation.

More: [The REST API, Access classes](../agents/rest-api.md#access-classes)

### Which operations need no sign-in?

The 12 in the `public` class: sign-up, sign-in, the emailed-link steps,
the invitation preview, the contract and the two service endpoints.

More: [The REST API, Access classes](../agents/rest-api.md#access-classes)

### What is a delegated operation?

An operation that a browser session may call, or a credential that holds
the operation's scope. There are 82.

More: [The REST API, Access classes](../agents/rest-api.md#access-classes)

### What is a session operation?

An operation only a person signed in with a browser may call. No
credential can call it, whatever its scopes. There are 78.

More: [The REST API, Access classes](../agents/rest-api.md#access-classes)

### What does "needs a person in a browser" mean?

The operation is in the `session` class. The request must carry the
session cookie of someone who signed in with their email and password, and
it must come from the Talewright web app.

More: [The REST API, What "needs a person in a browser" means](../agents/rest-api.md#what-needs-a-person-in-a-browser-means)

### Why is an operation browser only?

For one of four reasons: it controls credentials, it controls who can
access what, it deletes for good, or it is the step where a person reviews
what an agent prepared.

More: [The REST API, What "needs a person in a browser" means](../agents/rest-api.md#what-needs-a-person-in-a-browser-means)

### What does the reason `CREDENTIAL_CONTROL` cover?

22 operations: signing out, your account and sessions, sending feedback, API keys, connected
apps, consent to an app, and an organization's oversight of credentials.

More: [The REST API, Access classes](../agents/rest-api.md#access-classes)

### What does the reason `ACCESS_CONTROL` cover?

48 operations: 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.

More: [The REST API, Access classes](../agents/rest-api.md#access-classes)

### What does the reason `PERMANENT_DELETE` cover?

6 operations: deleting a trashed file or folder for good, and emptying the
trash, each in a workspace and in the organization folder.

More: [The REST API, Access classes](../agents/rest-api.md#access-classes)

### What does the reason `HUMAN_APPROVAL` cover?

2 operations: applying a library proposal, in a workspace and in the
organization folder. A bearer token gets `HUMAN_APPROVAL_REQUIRED` there.

More: [The REST API, Access classes](../agents/rest-api.md#access-classes)

### How do I see in the contract whether a script may call an operation?

Read `x-access.class` on the operation. `delegated` means a credential
with the scope may call it. `session` means browser only.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### 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`.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### Which scopes can a delegated operation name?

One of `workspace:read`, `files:read`, `files:write`, `files:approve`, or
`any` for the two operations every live credential may call.

More: [The REST API, Access classes](../agents/rest-api.md#access-classes)

### Can an owner's key with all four scopes call a browser-only operation?

No. No API key and no connected app can call it, even one that holds all
four scopes and acts for an owner.

More: [The REST API, What "needs a person in a browser" means](../agents/rest-api.md#what-needs-a-person-in-a-browser-means)

### Can a script create a public link through the API?

No. Making a file or a folder public or restricted is browser only, for
the reason `ACCESS_CONTROL`.

More: [Roles and permissions, Files in a workspace](../reference/permissions.md#files-in-a-workspace)

### Can a script purge the trash through the API?

No. Deleting a trashed file or folder for good and emptying the trash are
browser only. A script can move things to the trash and restore them.

More: [Roles and permissions, What only a person in a browser can do](../reference/permissions.md#what-only-a-person-in-a-browser-can-do)

### Can a browser session call the operations a script can call?

Yes. A browser session can call every operation its person's role allows,
delegated operations included. One exception: `GET /v1/credential`
describes a bearer credential and answers `401` to a session.

More: [The REST API, Signing in with a browser session](../agents/rest-api.md#signing-in-with-a-browser-session)

## Tenancy

### Does the API reveal whether an ID exists in another organization?

No. 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`.

More: [The REST API, Tenancy](../agents/rest-api.md#tenancy)

### Are IDs in request bodies and cursors checked like IDs in the path?

Yes. Every ID is checked against what the caller reaches, in paths, in
query parameters, in bodies and in cursors.

More: [The REST API, Tenancy](../agents/rest-api.md#tenancy)

### What does an ID with a typo answer?

`404 NOT_FOUND`, the same as a well-formed ID that does not exist.

More: [The REST API, Edge cases](../agents/rest-api.md#edge-cases)

## Errors and handling answers

### Where are the API's errors documented?

Every error has the same JSON body, with `error.code`, `error.message`,
`error.details` and `requestID`. The 20 codes, with every reason, are in
the errors reference. In the contract, `ErrorEnvelope` is the body and
`ErrorCode` lists the codes.

More: [The REST API, Errors](../agents/rest-api.md#errors)

### Do errors over MCP have the same shape as errors over REST?

Yes. A failed tool call returns a result with `isError: true`, and its
`structuredContent` is the same error envelope a REST call answers.

More: [MCP, Tool results](../agents/mcp.md#tool-results)

### How should a script handle the API's answers?

1. `2xx`: done.
2. `429`: wait `Retry-After` seconds, then send again.
3. `409 STALE_LOCK_VERSION`: read the thing again, rebuild the change.
4. `503` or `500`: wait briefly, send the same body again, give up after
   a few tries.
5. `401`: the key is no longer valid. Stop.
6. `403`, `404`, `422`, other `409`: do not repeat it unchanged.

More: [The REST API, Worked example](../agents/rest-api.md#worked-example)

## Paging

### How do I read every page of a list?

Pass each answer's `nextCursor` as `cursor`, with the same other
parameters, until `nextCursor` is `null`.

More: [The REST API, Paging](../agents/rest-api.md#paging)

### Which parameters do lists take for paging?

Two query parameters: `limit` (1 to 100, default 50) and `cursor`.

More: [The REST API, Paging](../agents/rest-api.md#paging)

### What does a list answer look like?

`{ "items": [...], "nextCursor": "..." }`. `nextCursor` is `null` on the
last page.

More: [The REST API, Paging](../agents/rest-api.md#paging)

### Can I build or change a cursor myself?

No. A cursor is opaque. Do not build or change one.

More: [The REST API, Paging](../agents/rest-api.md#paging)

### Can I use a cursor from one list on another list?

No. A cursor belongs to the list it came from. Used on another
workspace's list, it never returns the first workspace's items.

More: [The REST API, Paging](../agents/rest-api.md#paging)

### Can paging skip or repeat items?

No. The order of a list is stable, so paging neither skips nor repeats
items that did not change.

More: [The REST API, Paging](../agents/rest-api.md#paging)

### What happens with `limit=0` or `limit=101`?

`422 VALIDATION_FAILED` on `limit`. An invalid `cursor` answers the same
code on `cursor`.

More: [The REST API, Edge cases](../agents/rest-api.md#edge-cases)

### Which lists are not paged?

A few short lists answer only `items`: the workspaces a credential
reaches, the statuses, the status counts of one place, the fields,
favorites and deleted workspaces.

More: [The REST API, Paging](../agents/rest-api.md#paging)

### How do I count files when lists have no total?

Page through, or read the counts that other operations give, such as a
folder's `fileCount` or a status's `fileCount`.

More: [The REST API, Questions and answers](../agents/rest-api.md#questions-and-answers)

### Why does my script read other file counts than I see in the app?

Some counts depend on who asks. In the status list, the counts cover the
organization folder and the workspaces the caller can open: for a
credential, only the workspaces it is limited to.

More: [The REST API, Paging](../agents/rest-api.md#paging)

## Lock versions

### What is a lock version?

A whole number on every file and every folder, `lockVersion`. It stops a
second change from silently overwriting the first when two people, or a
person and an agent, change the same thing.

More: [The REST API, Lock versions](../agents/rest-api.md#lock-versions)

### Where do I send `expectedLockVersion`?

In a `PATCH` it is a body property. In a `DELETE` (move to trash) it is a
query parameter.

More: [The REST API, Lock versions](../agents/rest-api.md#lock-versions)

### What happens when I leave out `expectedLockVersion`?

The request answers `422 VALIDATION_FAILED`. A change to a file or folder
must send the `lockVersion` it was based on.

More: [The REST API, Lock versions](../agents/rest-api.md#lock-versions)

### What happens when `expectedLockVersion` matches?

The change is applied and the answer carries the new `lockVersion`.

More: [The REST API, Lock versions](../agents/rest-api.md#lock-versions)

### When does a file's `lockVersion` move?

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.

More: [The REST API, Lock versions](../agents/rest-api.md#lock-versions)

### Does uploading a new version of a file move its `lockVersion`?

No. A file's `lockVersion` does not move when the file gets a new version.

More: [The REST API, Lock versions](../agents/rest-api.md#lock-versions)

### What happens when two agents rename the same file at once?

One wins. The other gets `409 STALE_LOCK_VERSION` and must read the file
again.

More: [The REST API, Lock versions](../agents/rest-api.md#lock-versions)

### Can I overwrite a file's details without sending a lock version?

No. There is no way to force a change. Read the file, then send the change
with the `lockVersion` you read.

More: [The REST API, Lock versions](../agents/rest-api.md#lock-versions)

### Do the operations on many files take a lock version?

No. Setting a status or a field on up to 100 files takes no lock version.
They set one value and are safe to repeat.

More: [The REST API, Lock versions](../agents/rest-api.md#lock-versions)

### How does the API protect a file's bytes from being overwritten unseen?

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`.

More: [The REST API, Lock versions](../agents/rest-api.md#lock-versions)

## Safe retries with `requestID`

### What is `requestID` in a create for?

It makes repeating a create safe. A network failure can hide whether a
create went through; the same request with the same `requestID` does not
create a second thing.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### Which operations take a `requestID`?

Six creates: creating a folder, starting an upload and creating an
organization folder proposal, each in a workspace and in the organization
folder.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### Is `requestID` required over REST?

No. Over REST it is optional. Over MCP it is required.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### Which characters can a `requestID` hold?

Letters, digits, `-` and `_`. Anything else answers `422
VALIDATION_FAILED` on `requestID`.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### What does a repeated create with the same `requestID` answer?

`201` with what the first request created, as it is now. If the thing was
renamed since, the answer shows its new name.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### What happens when two copies of a create arrive at the same time?

One thing is created, when both copies carry the same `requestID`. The
second answers with what the first made.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### What happens when I send the same `requestID` with a different body?

`409 CONFLICT` with reason `REQUEST_REUSED`. The same holds for the same
`requestID` in another workspace.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### Can a colleague's `requestID` collide with mine?

No. A `requestID` is yours. Another member using the same string is not
affected by it.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### Is a `requestID` used up when the create is refused?

No. A `requestID` is remembered only when the create went through. After
a refusal such as `422`, the same `requestID` can be sent again, with the
same body or a corrected one.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### What happens when I repeat a create with its `requestID` after 24 hours?

A second thing is created. After 24 hours a `requestID` is forgotten and
counts as new.

More: [The REST API, Edge cases](../agents/rest-api.md#edge-cases)

### Do I need a `requestID` on every write?

No. Only six creates take it. Changes use `expectedLockVersion` instead,
and replacements use `baseVersionID`.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### Are `PUT` requests safe to repeat?

Yes. `PUT` operations, such as reordering and general access, set a
state; setting it twice changes nothing more.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### Is setting a status twice harmful?

No. Setting the same status or field value again changes nothing more.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

### Does a repeated proposal create still work after one of its files was trashed?

Yes. It answers with the first proposal. The repeat is matched to the
first request before its files are looked at.

More: [The REST API, Safe retries with `requestID`](../agents/rest-api.md#safe-retries-with-requestid)

## Request IDs for tracing

### What is the `x-request-id` header?

A tracing ID that every response carries. Every error body repeats the
same value as `requestID`.

More: [The REST API, Request IDs for tracing](../agents/rest-api.md#request-ids-for-tracing)

### Is the `requestID` of a create the same thing as `x-request-id`?

No. `requestID` in a create's body is your key for a safe retry.
`x-request-id` is a tracing ID of one request.

More: [The REST API, Request IDs for tracing](../agents/rest-api.md#request-ids-for-tracing)

### Can I send my own `x-request-id`?

Yes: up to 128 letters, digits, `-`, `_`, `.` or `:`. It is then used as
is.

More: [The REST API, Request IDs for tracing](../agents/rest-api.md#request-ids-for-tracing)

### What happens to an `x-request-id` with spaces?

It is dropped and a generated ID is used instead.

More: [The REST API, Edge cases](../agents/rest-api.md#edge-cases)

### Do audit events carry the request ID?

Yes. Audit events recorded during the request carry the same ID, so an
answer can be matched to the events that request recorded.

More: [Audit trail, What an event holds](../reference/audit-trail.md#what-an-event-holds)

## Rate limits and headers

### What should a script do when it gets `429`?

Wait the number of seconds in the `Retry-After` header, then send the
request again. `details.retryAfterSeconds` holds the same number.

More: [The REST API, Rate limiting](../agents/rest-api.md#rate-limiting)

### Which headers does a rate-limited answer carry?

`Retry-After`: whole seconds to wait, at least 1. There are no other rate
limit headers. No header tells you the limit, how much is left or when the
window resets.

More: [The REST API, Rate limiting](../agents/rest-api.md#rate-limiting)

### Can one busy API key slow down my colleagues' keys?

Yes. All credentials of one organization together may make 3,000 requests
a minute. A key that uses much of that leaves less for the others.

More: [The REST API, Rate limiting](../agents/rest-api.md#rate-limiting)

### Do sign-in and sign-up have the same rate limits as API keys?

No. Sign-in, sign-up, emailed links, invitations and key creation have
their own limits.

More: [The REST API, Rate limiting](../agents/rest-api.md#rate-limiting)

## Caching

### Which API answers must not be cached?

An answer that carries a key, from creating or rotating an API key. It is
sent with `Cache-Control: no-store`.

More: [The REST API, Answers you must not cache](../agents/rest-api.md#answers-you-must-not-cache)

### Should I store a temporary file address for later?

No. A temporary file address works for 10 minutes. Ask for a new one
instead of keeping it.

More: [The REST API, Answers you must not cache](../agents/rest-api.md#answers-you-must-not-cache)

### Does a temporary file address support `If-None-Match`?

Yes. While the address works, a request whose `If-None-Match` names the
`ETag` it answered before gets `304 Not Modified` without a body.

More: [The REST API, Answers you must not cache](../agents/rest-api.md#answers-you-must-not-cache)

## The OpenAPI contract

### Where is the OpenAPI contract?

At `https://app.usetalewright.com/v1/openapi.json`. `GET` answers it as an
OpenAPI 3.1 document.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### Do I need to sign in to read the OpenAPI contract?

No. Anyone can read it without signing in.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### What is a capability ID?

The unique name of one action of the product, such as
`workspace.files.search`. Each operation carries it as `x-capability`. With
the dots replaced by underscores it is the MCP tool name.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### What does `x-access` say on an operation?

The access class: `{"class": "public"}`,
`{"class": "session", "reason": "..."}` or
`{"class": "delegated", "scope": "..."}`.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### What does `x-mcp` say on an operation?

Whether the operation is an MCP tool: `none`, `tool` or `tool+resource`.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### What is `operationId` for?

It is a name for generated clients, such as `list_files`.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### Which security schemes does the contract define?

Two: `session`, the cookie `__Host-session`, and `apiKey`, HTTP bearer in
the format `ak1_<public ID>_<secret>`.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### How are operations grouped in the contract?

By tag: `auth`, `account`, `files`, `organizations`, `credentials` and
`operations`.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### Does the contract say which errors an operation can answer?

Yes. `responses` on each operation lists every status it answers, each
with the codes and reasons it can carry.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### Where does the contract define the error body?

In `components.schemas`: `ErrorEnvelope` is the error body and `ErrorCode`
lists the 20 codes.

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### How do I list every operation a `files:write` key may call?

Filter the contract by access class and scope:

```sh
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"])"'
```

More: [The REST API, Reading the OpenAPI contract](../agents/rest-api.md#reading-the-openapi-contract)

### Can I generate a client from the contract?

Yes. The contract is a standard OpenAPI 3.1 document, and client
generators work with it. Talewright's own web app uses a client generated
from it.

More: [The REST API, Questions and answers](../agents/rest-api.md#questions-and-answers)

## Uploading through the API

### How do I upload a file through the REST API?

In three steps:

1. **Start.** `POST /v1/workspaces/{workspaceID}/uploads` with `fileName`,
   `sizeBytes` and `contentType`. The answer holds `partSizeBytes`,
   `partCount` and the addresses of the first 100 parts in `partURLs`.
2. **Send.** `PUT` each part to its `url` and keep each answer's `ETag`.
3. **Complete.** `POST .../uploads/{uploadID}/complete` with
   `{"parts": [{"partNumber": 1, "etag": "..."}, ...]}`, then read the
   upload until it is `ready` or `rejected`.

More: [Uploading, The three steps](../files/uploading.md#the-three-steps)

### What do I send to start an upload?

`fileName`, `sizeBytes` and `contentType` are required. `folderID`,
`sha256`, `requestID`, and `targetFileID` with `baseVersionID` for a
replacement, are optional.

More: [Uploading, What you declare when starting](../files/uploading.md#what-you-declare-when-starting)

### What does starting an upload return?

An upload in the state `pending`, with the size of its parts
(`partSizeBytes`), how many there are (`partCount`), the addresses of the
first 100 parts (`partURLs`) and the time it expires unless completed
(`expiresAt`, 24 hours on).

More: [Uploading, The three steps](../files/uploading.md#the-three-steps)

### How do I send the bytes of an upload?

Part by part, each with one HTTP `PUT` to its address. A file of up to
16 MiB is one part. Keep the `ETag` header of each answer.

```sh
curl -s -X PUT "$PART_URL" --data-binary @press-photo.jpg -D - -o /dev/null
```

More: [Uploading, Worked example](../files/uploading.md#worked-example)

### Should the `PUT` of an upload carry my API key?

No. Send no `Authorization` header: the address is the permission. Treat
each part's address as a secret for as long as it works.

More: [Uploading, Worked example](../files/uploading.md#worked-example)

### What happens when a part's `PUT` has another length than the part's `sizeBytes`?

It is refused with `403`. The address accepts exactly that part's number of
bytes.

More: [Uploading, Parts and their addresses](../files/uploading.md#parts-and-their-addresses)

### How do I complete an upload?

`POST /v1/workspaces/{workspaceID}/uploads/{uploadID}/complete` with the
API key and `{"parts": [...]}`, each part with its `ETag`. It answers `202`
with the upload, now `verifying`.

More: [Uploading, Completing](../files/uploading.md#completing)

### How do I know when an upload through the API is done?

Read `GET /v1/workspaces/{workspaceID}/uploads/{uploadID}` until `state` is
`ready` or `rejected`, waiting a little longer between reads each time.
When `ready`, `fileID` and `versionID` name the new file and its version.

More: [Uploading, Worked example](../files/uploading.md#worked-example)

### Can I upload a file in one request with `multipart/form-data`?

No. The bytes never go through the API. Each part goes straight to its
address with an ordinary HTTP `PUT`, between the start and the complete
request.

More: [Uploading, Operations](../files/uploading.md#operations)

### Can I upload a large file in several parts?

Yes. Every upload is sent in parts of 16 MiB, up to 50 GiB, in any order and
several at once. `POST .../uploads/{uploadID}/part-urls` signs addresses
past the first 100, and `GET .../uploads/{uploadID}/parts` lists what is
already stored, so an interrupted upload resumes.

More: [Uploading, Parts and their addresses](../files/uploading.md#parts-and-their-addresses)

### Can the API fetch a file from a URL for me?

No. An upload declares a name, a size and a type, and you send the bytes
yourself to the part addresses.

More: [Uploading, What you declare when starting](../files/uploading.md#what-you-declare-when-starting)

### Is a too-large file refused before I send its bytes?

Yes. The size limit is checked when the upload starts, before any byte is
sent. A larger declared size answers `413 PAYLOAD_TOO_LARGE` with
`details.limitBytes`.

More: [Uploading, Size limits](../files/uploading.md#size-limits)

### Which is checked first when an upload starts, the size or the type?

The size. A file that is both too large and of an unaccepted type is
refused for its size.

More: [Uploading, What you declare when starting](../files/uploading.md#what-you-declare-when-starting)

### Does Talewright change the bytes I upload?

No. The bytes are stored exactly as they were sent. Nothing is stripped,
converted or recompressed.

More: [Uploading, The three steps](../files/uploading.md#the-three-steps)

### When does an uploaded file show up in file listings?

Only after the upload is `ready`. A file never appears in a listing while
it is still being sent or checked.

More: [Uploading, The three steps](../files/uploading.md#the-three-steps)

### How do I replace a file's bytes through the API?

Start an upload with `targetFileID` and `baseVersionID`, always together,
and no `folderID`. The upload then makes a new version of that file.

More: [Uploading, What you declare when starting](../files/uploading.md#what-you-declare-when-starting)

### How do I upload into the organization folder through the API?

Use the library path, `POST /v1/organizations/{organizationID}/library/uploads`.
The key needs `files:write`, and its member must be an owner or admin.

More: [Uploading, Operations](../files/uploading.md#operations)

### How does a script find its uploads again after a restart?

`GET /v1/workspaces/{workspaceID}/uploads?active=true` lists your own
uploads that are `pending` or `verifying`, newest first.

More: [Uploading, Operations](../files/uploading.md#operations)

### How do I cancel an upload through the API?

`DELETE /v1/workspaces/{workspaceID}/uploads/{uploadID}`, with
`files:write`. Only a pending upload can be cancelled.

More: [Uploading, Operations](../files/uploading.md#operations)

### Which scopes do the upload operations need?

Starting, completing and cancelling need `files:write`. Reading and
listing your uploads need `files:read`.

More: [Uploading, Operations](../files/uploading.md#operations)

### What should a script do when the complete request times out?

Send it again. Completing an upload that is already `verifying`, `ready`
or `rejected` answers `202` with the upload unchanged.

More: [Uploading, Completing](../files/uploading.md#completing)

### What should a script do when a part's address stopped working?

If the upload is still `pending`, sign that part again with
`POST .../uploads/{uploadID}/part-urls`. Past `expiresAt`, start a new
upload.

More: [Uploading, Worked example](../files/uploading.md#worked-example)

## Downloading through the API

### How do I download a file's bytes through the REST API?

Either `GET /v1/workspaces/{workspaceID}/files/{fileID}/versions/{versionID}/content`
with the API key, or ask for a signed link and fetch that. Both need
`files:read`.

More: [Downloading, Operations](../files/downloading.md#operations)

### Which headers does the content operation answer with?

`Content-Disposition: attachment`, `Content-Type`, `Content-Length`,
`ETag` with the version's digest written `"sha256:<hex>"`, and
`Cache-Control: private, no-cache`.

More: [Downloading, Downloading through the API](../files/downloading.md#downloading-through-the-api)

### Can I download part of a file with a `Range` header?

Yes. The content operation takes an optional `Range` header and answers
`206` with the range.

More: [Downloading, Requests and answers](../files/downloading.md#requests-and-answers)

### Can I download an earlier version of a file through the API?

Yes. The content operation works for every version of a file, current or
earlier. The version must belong to the file, or the answer is `404
NOT_FOUND`.

More: [Downloading, Downloading through the API](../files/downloading.md#downloading-through-the-api)

### Can I download a file that is in the trash through the API?

Yes, with the content operation, until that file is deleted for good.

More: [Downloading, Downloading through the API](../files/downloading.md#downloading-through-the-api)

### How do I ask for a signed link over REST?

`POST /v1/workspaces/{workspaceID}/files/{fileID}/versions/{versionID}/signed-url`
with `{"variant": "original"}`, or `thumb`, `preview` or `playback`. The
answer holds `url` and `expiresAt`.

More: [Downloading, Requests and answers](../files/downloading.md#requests-and-answers)

### How do I download several files as one ZIP through the API?

`POST /v1/workspaces/{workspaceID}/files/archive` with
`{"folderIDs": [...], "fileIDs": [...]}`, at least one ID. The answer holds
`url`, `expiresAt`, `name`, `fileCount` and `sizeBytes`.

More: [Downloading, ZIP downloads](../files/downloading.md#zip-downloads)

### Is a ZIP download through the API recorded?

Yes. Asking for a ZIP is recorded in the audit trail as
`files.archive_downloaded`, with the number of folders, files and bytes.

More: [Downloading, ZIP downloads](../files/downloading.md#zip-downloads)

## Common tasks with `curl`

### How do I find out what my API key reaches?

```sh
curl -s https://app.usetalewright.com/v1/workspaces \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

The answer lists each workspace with `id`, `name`, `organizationID` and
`organizationName`.

More: [The REST API, Worked example](../agents/rest-api.md#worked-example)

### How do I list the files of a workspace with `curl`?

```sh
curl -s "https://app.usetalewright.com/v1/workspaces/$WORKSPACE/files?type=image&limit=20" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

While `nextCursor` is not `null`, repeat with `&cursor=$NEXT_CURSOR`.

More: [The REST API, Worked example](../agents/rest-api.md#worked-example)

### How do I create a folder through the API?

```sh
curl -s -X POST "https://app.usetalewright.com/v1/workspaces/$WORKSPACE/folders" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Press kit 2026", "requestID": "press-kit-folder-1"}'
```

The `requestID` makes sure a retry cannot create two.

More: [The REST API, Worked example](../agents/rest-api.md#worked-example)

### How do I rename a file through the API?

`PATCH` the file with the `lockVersion` you read and the new name:

```sh
curl -s -X PATCH "https://app.usetalewright.com/v1/workspaces/$WORKSPACE/files/$FILE" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedLockVersion": 3, "name": "logo-dark-2026.svg"}'
```

More: [The REST API, Worked example](../agents/rest-api.md#worked-example)

### How do I move a file to the trash through the API?

`DELETE` the file with `expectedLockVersion` as a query parameter:

```sh
curl -s -X DELETE "https://app.usetalewright.com/v1/workspaces/$WORKSPACE/files/$FILE?expectedLockVersion=4" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

More: [The REST API, Worked example](../agents/rest-api.md#worked-example)

### Which operation sets a status on files over REST?

`POST /v1/workspaces/{workspaceID}/files/status`, or
`POST /v1/organizations/{organizationID}/library/files/status` for the
organization folder. It is the capability `workspace.files.status.set` and needs
`files:approve`.

More: [MCP, Every tool](../agents/mcp.md#every-tool)

### Which operation sets one field on many files over REST?

`POST /v1/workspaces/{workspaceID}/files/fields`, the capability
`workspace.files.fields.set`. It needs `files:write` and takes 1 to 100
files.

More: [MCP, Every tool](../agents/mcp.md#every-tool)

### Which operation restores a file from the trash over REST?

`POST /v1/workspaces/{workspaceID}/files/{fileID}/restore`, the capability
`workspace.files.restore`. It needs `files:write`.

More: [MCP, Every tool](../agents/mcp.md#every-tool)
