RESTful management API for programmatically creating and managing Turso Cloud databases, groups, organizations, locations, and scoped authentication tokens. Used for building multi-tenant architectures, automating database provisioning on user signup or agent creation, and managing the full lifecycle of libSQL databases in the cloud.
openapi: 3.0.1
info:
title: Turso Platform API
description: API description here
license:
name: MIT
version: 0.1.0
servers:
- url: https://api.turso.tech
description: Turso's Platform API
paths:
/v1/organizations/{organizationSlug}/databases:
get:
summary: List Databases
description: Returns a list of databases belonging to the organization or user.
operationId: listDatabases
parameters:
- $ref: '#/components/parameters/organizationSlug'
- name: group
in: query
schema:
type: string
description: Filter databases by group name.
- name: schema
in: query
schema:
type: string
description: The schema database name that can be used to get databases that
belong to that parent schema.
deprecated: true
- name: parent
in: query
schema:
type: string
description: Filter database branches by using their parent database ID.
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
databases:
type: array
items:
$ref: '#/components/schemas/Database'
post:
summary: Create Database
description: Creates a new database in a group for the organization or user.
operationId: createDatabase
parameters:
- $ref: '#/components/parameters/organizationSlug'
requestBody:
description: Database data to create a new database
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatabaseInput'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
database:
$ref: '#/components/schemas/CreateDatabaseOutput'
description: The newly created database
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message
example: group not found
'409':
description: Conflict
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message
example: database with name [databaseName] already exists
/v1/organizations/{organizationSlug}/databases/{databaseName}:
get:
summary: Retrieve Database
description: Returns a database belonging to the organization or user.
operationId: getDatabase
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/databaseName'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
database:
$ref: '#/components/schemas/Database'
'404':
$ref: '#/components/responses/DatabaseNotFoundResponse'
delete:
summary: Delete Database
description: Delete a database belonging to the organization or user.
operationId: deleteDatabase
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/databaseName'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
database:
type: string
description: The name of the database that was deleted.
example: my-db
'404':
$ref: '#/components/responses/DatabaseNotFoundResponse'
/v1/organizations/{organizationSlug}/databases/{databaseName}/configuration:
get:
summary: Retrieve Database Configuration
description: Retrieve an individual database configuration belonging to the
organization or user.
operationId: getDatabaseConfiguration
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/databaseName'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseConfigurationResponse'
patch:
summary: Update Database Configuration
description: Update a database configuration belonging to the organization or
user.
operationId: updateDatabaseConfiguration
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/databaseName'
requestBody:
description: The configuration to be applied to the chosen database.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseConfigurationInput'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseConfigurationResponse'
/v1/organizations/{organizationSlug}/databases/{databaseName}/instances:
get:
summary: List Database Instances
description: Returns a list of instances of a database. Instances are the individual
primary or replica databases in each region defined by the group.
operationId: listDatabaseInstances
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/databaseName'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
instances:
type: array
items:
$ref: '#/components/schemas/Instance'
/v1/organizations/{organizationSlug}/databases/{databaseName}/instances/{instanceName}:
get:
summary: Retrieve Database Instance
description: Return the individual database instance by name.
operationId: getDatabaseInstance
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/databaseName'
- $ref: '#/components/parameters/instanceName'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
instance:
$ref: '#/components/schemas/Instance'
/v1/organizations/{organizationSlug}/databases/{databaseName}/auth/tokens:
post:
summary: Generate Database Auth Token
description: Generates an authorization token for the specified database.
operationId: createDatabaseToken
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/databaseName'
- name: expiration
in: query
schema:
type: string
default: never
description: Expiration time for the token (e.g., 2w1d30m).
- name: authorization
in: query
schema:
type: string
default: full-access
enum:
- full-access
- read-only
description: Authorization level for the token (full-access or read-only).
requestBody:
description: Additional context such as claims required for the token.
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTokenInput'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
jwt:
type: string
description: The generated authorization token (JWT).
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message
example: Invalid expiration format
'404':
$ref: '#/components/responses/DatabaseNotFoundResponse'
/v1/organizations/{organizationSlug}/databases/{databaseName}/usage:
get:
summary: Retrieve Database Usage
description: Fetch activity usage for a database in a given time period.
operationId: getDatabaseUsage
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/databaseName'
- name: from
in: query
schema:
type: string
format: date-time
description: 'The datetime to retrieve usage **from** in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
format. Defaults to the current calendar month if not provided. Example:
`2023-01-01T00:00:00Z`'
- name: to
in: query
schema:
type: string
format: date-time
description: 'The datetime to retrieve usage **to** in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
format. Defaults to the current calendar month if not provided. Example:
`2023-02-01T00:00:00Z`'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
database:
type: object
description: The database usage object, containg the total and
individual instance usage for rows read and written, as well
as the total storage size (in bytes).
$ref: '#/components/schemas/DatabaseUsageOutput'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message
example: 'invalid from parameter: parsing time "2023-12-12T00:00:00"
as "2006-01-02T15:04:05Z07:00": cannot parse "" as "Z07:00"'
'404':
$ref: '#/components/responses/DatabaseNotFoundResponse'
/v1/organizations/{organizationSlug}/databases/{databaseName}/stats:
get:
summary: Retrieve Database Stats
description: Fetch the top queries of a database, including the count of rows
read and written.
operationId: getDatabaseStats
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/databaseName'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
top_queries:
type: array
description: The top queries performed on the given database as
well as the total rows read and written.
nullable: true
items:
$ref: '#/components/schemas/DatabaseStatsOutput'
'404':
$ref: '#/components/responses/DatabaseNotFoundResponse'
/v1/organizations/{organizationSlug}/databases/{databaseName}/auth/rotate:
post:
summary: Invalidate All Database Auth Tokens
description: Invalidates all authorization tokens for the specified database.
operationId: invalidateDatabaseTokens
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/databaseName'
responses:
'200':
description: Successful response (No Content)
'404':
$ref: '#/components/responses/DatabaseNotFoundResponse'
/v1/organizations/{organizationSlug}/groups:
get:
summary: List Groups
description: Returns a list of groups belonging to the organization or user.
operationId: listGroups
parameters:
- $ref: '#/components/parameters/organizationSlug'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
groups:
type: array
items:
$ref: '#/components/schemas/Group'
post:
summary: Create Group
description: Creates a new group for the organization or user.
operationId: createGroup
parameters:
- $ref: '#/components/parameters/organizationSlug'
requestBody:
description: Group data to create a new group
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewGroup'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
group:
$ref: '#/components/schemas/Group'
description: The newly created group
'409':
description: Conflict
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message
example: group already exists
/v1/organizations/{organizationSlug}/groups/{groupName}:
get:
summary: Retrieve Group
description: Returns a group belonging to the organization or user.
operationId: getGroup
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/groupName'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
group:
$ref: '#/components/schemas/Group'
'404':
$ref: '#/components/responses/GroupNotFoundResponse'
delete:
summary: Delete Group
description: Delete a group belonging to the organization or user.
operationId: deleteGroup
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/groupName'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
group:
$ref: '#/components/schemas/Group'
'404':
$ref: '#/components/responses/GroupNotFoundResponse'
/v1/organizations/{organizationSlug}/groups/{groupName}/configuration:
get:
summary: Retrieve Group Configuration
description: Retrieve an individual group configuration belonging to the organization
or user.
operationId: getGroupConfiguration
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/groupName'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GroupConfigurationResponse'
patch:
summary: Update Group Configuration
description: Update a group configuration belonging to the organization or user.
operationId: updateGroupConfiguration
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/groupName'
requestBody:
description: The configuration to be applied to the chosen group.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupConfigurationInput'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GroupConfigurationResponse'
/v1/organizations/{organizationSlug}/groups/{groupName}/transfer:
post:
summary: Transfer Group
description: Transfer a group to another organization that you own or a member
of.
operationId: transferGroup
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/groupName'
requestBody:
description: Receiving Organization details.
required: true
content:
application/json:
schema:
type: object
properties:
organization:
type: string
description: The slug of the organization to transfer the group
to.
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'404':
$ref: '#/components/responses/GroupNotFoundResponse'
/v1/organizations/{organizationSlug}/groups/{groupName}/unarchive:
post:
summary: Unarchive Group
description: Unarchive a group that has been archived due to inactivity.
operationId: unarchiveGroup
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/groupName'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
group:
$ref: '#/components/schemas/Group'
description: The group that was unarchived
'404':
$ref: '#/components/responses/GroupNotFoundResponse'
/v1/organizations/{organizationSlug}/groups/{groupName}/locations/{location}:
post:
summary: Add Location to Group
description: Adds a location to the specified group.
operationId: addLocationToGroup
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/groupName'
- name: location
in: path
required: true
schema:
type: string
description: The location code to add to the group.
example: aws-us-east-1
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
group:
$ref: '#/components/schemas/Group'
description: The group with the added location
example:
group:
archived: false
locations:
- aws-us-east-1
- aws-eu-west-1
name: default
primary: aws-us-east-1
uuid: f1dec998-8f7f-11ee-907d-a2a821fd08b9
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message
example: 'invalid location: amss'
'404':
$ref: '#/components/responses/GroupNotFoundResponse'
delete:
summary: Remove Location from Group
description: Removes a location from the specified group.
operationId: removeLocationFromGroup
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/groupName'
- name: location
in: path
required: true
schema:
type: string
description: The location code to remove from the group.
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
group:
$ref: '#/components/schemas/Group'
description: The group with the removed location
example:
group:
archived: false
locations:
- aws-us-east-1
- aws-eu-west-1
name: default
primary: aws-us-east-1
uuid: f1dec998-8f7f-11ee-907d-a2a821fd08b9
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message
example: Invalid location code
'404':
$ref: '#/components/responses/GroupNotFoundResponse'
/v1/organizations/{organizationSlug}/groups/{groupName}/update:
post:
summary: Update Databases in a Group
description: Updates all databases in the group to the latest libSQL version.
operationId: updateGroupDatabases
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/groupName'
responses:
'200':
description: Successful response (No Content)
'404':
$ref: '#/components/responses/GroupNotFoundResponse'
/v1/organizations/{organizationSlug}/groups/{groupName}/auth/tokens:
post:
summary: Create Group Auth Token
description: Generates an authorization token for the specified group.
operationId: createGroupToken
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/groupName'
- name: expiration
in: query
schema:
type: string
default: never
description: Expiration time for the token (e.g., 2w1d30m).
- name: authorization
in: query
schema:
type: string
default: full-access
enum:
- full-access
- read-only
description: Authorization level for the token (full-access or read-only).
requestBody:
description: Additional context such as claims required for the token.
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTokenInput'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
jwt:
type: string
description: The generated authorization token (JWT).
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message
example: Invalid expiration format
'404':
$ref: '#/components/responses/GroupNotFoundResponse'
/v1/organizations/{organizationSlug}/groups/{groupName}/auth/rotate:
post:
summary: Invalidate All Group Auth Tokens
description: Invalidates all authorization tokens for the specified group.
operationId: invalidateGroupTokens
parameters:
- $ref: '#/components/parameters/organizationSlug'
- $ref: '#/components/parameters/groupName'
responses:
'200':
description: Successful response (No Content)
'404':
$ref: '#/components/responses/GroupNotFoundResponse'
/v1/locations:
get:
summary: List Locations
description: Returns a list of locations where you can create or replicate databases.
operationId: listLocations
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
locations:
type: object
additionalProperties:
type: string
description: A mapping of location codes to location names.
example:
locations:
aws-ap-northeast-1: AWS AP NorthEast (Tokyo)
aws-ap-south-1: AWS AP South (Mumbai)
aws-eu-west-1: AWS EU West (Ireland)
aws-us-east-1: AWS US East (Virginia)
aws-us-east-2: AWS US East (Ohio)
aws-us-west-2: AWS US West (Oregon)
/v1/organizations:
get:
summary: List Organizations
description: Returns a list of organizations the authenticated user owns or
is a member of.
operationId: listOrganizations
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Organization'
/v1/organizations/{organizationSlug}:
get:
summary: Retrieve Organization
description: Retrieve details of a specific organization.
operationId: getOrganization
parameters:
- $ref: '#/components/parameters/organizationSlug'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
organization:
$ref: '#/components/schemas/Organization'
'404':
description: Organization not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message
example: organization not found
patch:
summary: Update Organization
description: Update an organization you own or are a member of.
operationId: updateOrganization
parameters:
- $ref: '#/components/parameters/organizationSlug'
requestBody:
description: The updated organization details.
required: true
content:
application/json:
schema:
type: object
properties:
overages:
type: boolean
description: Enable or disable overages for the organization.
require_mfa:
type: boolean
description: Require all members of the organization to have multi-factor
authentication enabled. The requesting user must have MFA enabled
on their own account before enabling this requirement.
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
organization:
description: The updated organization.
$ref: '#/components/schemas/Organization'
/v1/organizations/{organizationSlug}/plans:
get:
summary: List Plans
description: Returns a list of available plans and their quotas.
operationId: listOrganizationPlans
parameters:
- $ref: '#/components/parameters/organizationSlug'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
plans:
type: array
description: List of available plans.
items:
$ref: '#/components/schemas/OrganizationPlan'
/v1/organizations/{organizationSlug}/invoices:
get:
summary: List Invoices
description: Returns a list of invoices for the organization.
operationId: listOrganizationInvoices
parameters:
- $ref: '#/components/parameters/organizationSlug'
- name: type
in: query
schema:
type: string
enum:
- all
- upcoming
- issued
description: The type of invoice to retrieve.
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
invoices:
type: array
description: The list of invoices for the organization.
items:
type: object
properties:
invoice_number:
type: string
description: The unique ID for the invoice.
example: LFONTK-00001
amount_due:
type: string
description: The formatted price in USD for the invoice.
example: '10.29'
due_date:
type: string
description: The due date for the invoice.
example: '2024-01-01T05:00:00+00:00'
paid_at:
type: string
description: The date the invoice was paid.
example: '2024-01-01T05:00:00+00:00'
payment_failed_at:
type: string
description: The date the invoice payment last failed.
example: '2024-01-01T05:00:00+00:00'
invoice_pdf:
type: string
description: The link to the invoice PDF you can download.
example: https://assets.withorb.com/invoice/...
/v1/organizations/{organizationSlug}/subscription:
get:
summary: Current Subscription
description: Returns the current subscription details for the organization.
operationId: getOrganizationSubscription
parameters:
- $ref: '#/components/parameters/organizationSlug'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
subscription:
type: object
properties:
name:
type: string
description: The name of the plan for the current subscription.
example: scaler
overages:
type: boolean
description: Whether overages are enabled for the organization.
plan:
type: string
description: The name of the plan for the current subscription.
example: scaler
timeline:
type: st
# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/turso/refs/heads/main/openapi/turso-platform-api-openapi.yml