# 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](../reference/permissions.md).
- 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](../files/downloading.md).
- 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](mcp.md) and
  [Connected apps](connected-apps.md).

### 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 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-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](credentials.md).
- 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.

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

| 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`, then `403`, then `422`.

### Errors

Every error has the same body:

```json
{
  "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](../reference/errors.md).

### 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](../files/statuses.md#counts).
- 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](../files/fields-and-tags.md).
- 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](../files/statuses.md#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](../files/library-and-suggestions.md).
- After 24 hours a `requestID` is 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-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](../reference/limits.md#rates).
- 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](../files/downloading.md#what-a-signed-link-serves).

## 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](credentials.md#in-the-app).
- 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:

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

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

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

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

```json
{
  "items": [
    {
      "id": "0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21",
      "name": "Keystone Main",
      "organizationID": "0192e7c4-0b22-7e61-9f32-5dab8b7e6f41",
      "organizationName": "Keystone"
    }
  ]
}
```

List files, 20 at a time:

```sh
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:

```sh
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:

```sh
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:

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

| 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](../reference/errors.md#conflict-409). |
| `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](#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.

## Related pages

- [Credentials and scopes](credentials.md)
- [Connected apps](connected-apps.md)
- [MCP](mcp.md)
- [Roles and permissions](../reference/permissions.md)
- [Errors](../reference/errors.md)
- [Limits](../reference/limits.md)
- [Audit trail](../reference/audit-trail.md)
- [Glossary](../reference/glossary.md)

