Turso Platform REST API
The Turso Platform REST API is used to perform actions on data and databases managed by Turso. The following groups of operations are available:
- Manage organizations
- Location discovery
- Manage logical databases
- Manage database instances
- Manage database groups
The API is served using HTTPS from the host
This API is used directly by the Turso CLI. However, the API does not operate exactly like the interface provided CLI. Each operation includes a reference to the analogous Turso CLI command, noting where there are significant differences in behavior.
Request and response
The API accepts variable inputs from placeholders in the URL path, the query string, and the HTTP body. HTTP request and response bodies are expressed as JSON objects unless otherwise specified.
API errors yield an HTTP response body containing a JSON object with a string property named "error".
Universal HTTP response codes
|200||OK - operation completed successfully|
|401||Unauthorized - ensure that the auth token is present and valid|
|402||Payment required - organization feature is not part of account plan|
|409||Conflict - resource already exists|
About the examples in this documentation
The examples use curl and assume the following shell variables were established ahead of time:
TURSO_TOKEN, read the section about authentication.
The Turso Platform API requires that all requests include an authentication token that identifies a user account. Operations are performed on behalf of this user using the permissions granted to that user.
The platform and user tokens mentioned above are different from the database tokens used to allow client application access to the database for the purpose of performing database queries. They are not interchangeable.
Platform API tokens
You can mint a platform API token in two ways:
User authentication tokens
The Turso Platform API also recognizes tokens granted to a user when they log
in to the Turso CLI using
turso auth login. After logging in, run
token to output the token string. These tokens expire after seven days, so they
are not suitable for use with non-interactive applications.
Provide a token to the API
All HTTP requests must include the token string in the
The header takes the following form:
Authorization: Bearer [token]
[token] is is a placeholder for either a platform or user token.