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.
The basics
- Does Talewright have an API?
- What is the base URL of the Talewright API?
- How is the API versioned?
- Is the API the same one the Talewright web app uses?
- Where is the API reference?
- Which operations can a script call?
- Is there a page for the API in the app?
- Does the API work over plain
http? - Are file bytes served from the API host?
- What are
/healthzand/readyz? - Are the MCP endpoint and the OAuth endpoints part of the REST API?
What the API does not have
- Does Talewright have webhooks?
- Is there an official SDK or client library?
- Does Talewright have a GraphQL API?
- Is there a sandbox or a test environment for the API?
- Is there a general batch endpoint for many requests at once?
- Does the API take an
Idempotency-Keyheader? - Can I call the API from JavaScript on my own website?
- Can I sign in to the API with OAuth?
- Does the API accept XML or form bodies?
- Can a list answer a total count or a page number?
Requests and responses
- What format do request and response bodies have?
- How are properties named in the API?
- What format do IDs have in the API?
- What format do dates and times have in the API?
- Which status codes does a successful request answer?
- What does a
202answer mean? - What happens when a request takes too long?
- Which characters can text I send not contain?
- Does the API trim the names I send?
- What does the API answer for the wrong method on an existing path?
- What does the API answer for a body that is not valid JSON?
Workspace paths and library paths
Authentication
- How do I authenticate a request to the API?
- Can I use my email and password from a script?
- Can I copy my browser's session cookie into a script?
- What is the session cookie called?
- Should my script send an
Originheader? - How does the API check where a changing request comes from?
- Can an API key call
GET /v1/me? - In what order is a request with an API key checked?
- Can someone without a valid key find out which operations are browser only?
- Does a public operation look at my API key?
- Does a failed authentication count against me?
Access classes and browser-only operations
- What is an access class?
- Which operations need no sign-in?
- What is a delegated operation?
- What is a session operation?
- What does "needs a person in a browser" mean?
- Why is an operation browser only?
- What does the reason
CREDENTIAL_CONTROLcover? - What does the reason
ACCESS_CONTROLcover? - What does the reason
PERMANENT_DELETEcover? - What does the reason
HUMAN_APPROVALcover? - How do I see in the contract whether a script may call an operation?
- How do I know which scope an operation needs?
- Which scopes can a delegated operation name?
- Can an owner's key with all four scopes call a browser-only operation?
- Can a script create a public link through the API?
- Can a script purge the trash through the API?
- Can a browser session call the operations a script can call?
Tenancy
Errors and handling answers
Paging
- How do I read every page of a list?
- Which parameters do lists take for paging?
- What does a list answer look like?
- Can I build or change a cursor myself?
- Can I use a cursor from one list on another list?
- Can paging skip or repeat items?
- What happens with
limit=0orlimit=101? - Which lists are not paged?
- How do I count files when lists have no total?
- Why does my script read other file counts than I see in the app?
Lock versions
- What is a lock version?
- Where do I send
expectedLockVersion? - What happens when I leave out
expectedLockVersion? - What happens when
expectedLockVersionmatches? - When does a file's
lockVersionmove? - Does uploading a new version of a file move its
lockVersion? - What happens when two agents rename the same file at once?
- Can I overwrite a file's details without sending a lock version?
- Do the operations on many files take a lock version?
- How does the API protect a file's bytes from being overwritten unseen?
Safe retries with requestID
- What is
requestIDin a create for? - Which operations take a
requestID? - Is
requestIDrequired over REST? - Which characters can a
requestIDhold? - What does a repeated create with the same
requestIDanswer? - What happens when two copies of a create arrive at the same time?
- What happens when I send the same
requestIDwith a different body? - Can a colleague's
requestIDcollide with mine? - Is a
requestIDused up when the create is refused? - What happens when I repeat a create with its
requestIDafter 24 hours? - Do I need a
requestIDon every write? - Are
PUTrequests safe to repeat? - Is setting a status twice harmful?
- Does a repeated proposal create still work after one of its files was trashed?
Request IDs for tracing
Rate limits and headers
Caching
The OpenAPI contract
- Where is the OpenAPI contract?
- Do I need to sign in to read the OpenAPI contract?
- What is a capability ID?
- What does
x-accesssay on an operation? - What does
x-mcpsay on an operation? - What is
operationIdfor? - Which security schemes does the contract define?
- How are operations grouped in the contract?
- Does the contract say which errors an operation can answer?
- Where does the contract define the error body?
- How do I list every operation a
files:writekey may call? - Can I generate a client from the contract?
Uploading through the API
- How do I upload a file through the REST API?
- What do I send to start an upload?
- What does starting an upload return?
- How do I send the bytes of an upload?
- Should the
PUTof an upload carry my API key? - What happens when a part's
PUThas another length than the part'ssizeBytes? - How do I complete an upload?
- How do I know when an upload through the API is done?
- Can I upload a file in one request with
multipart/form-data? - Can I upload a large file in several parts?
- Can the API fetch a file from a URL for me?
- Is a too-large file refused before I send its bytes?
- Which is checked first when an upload starts, the size or the type?
- Does Talewright change the bytes I upload?
- When does an uploaded file show up in file listings?
- How do I replace a file's bytes through the API?
- How do I upload into the organization folder through the API?
- How does a script find its uploads again after a restart?
- How do I cancel an upload through the API?
- Which scopes do the upload operations need?
- What should a script do when the complete request times out?
- What should a script do when a part's address stopped working?
Downloading through the API
- How do I download a file's bytes through the REST API?
- Which headers does the content operation answer with?
- Can I download part of a file with a
Rangeheader? - Can I download an earlier version of a file through the API?
- Can I download a file that is in the trash through the API?
- How do I ask for a signed link over REST?
- How do I download several files as one ZIP through the API?
- Is a ZIP download through the API recorded?
Common tasks with curl
- How do I find out what my API key reaches?
- How do I list the files of a workspace with
curl? - How do I create a folder through the API?
- How do I rename a file through the API?
- How do I move a file to the trash through the API?
- Which operation sets a status on files over REST?
- Which operation sets one field on many files over REST?
- Which operation restores a file from the trash over REST?