Skip to main content

​
Overview

You can use the PlanetScale API to manage your PlanetScale databases programmatically. The PlanetScale API does not include direct access to the data in the database. Some endpoints will consist of database schema information or connection information.

​
Base URL

Every endpoint is under https://api.planetscale.com/v1. Requests and responses are JSON.

​
Authentication

Before making your first API call, set up the proper authentication for the PlanetScale API using the Authorization header. There are two API authentication types: Service tokens and OAuth.

​
Service tokens

Send a service token as a Bearer token:
The API also accepts the token ID and token together, with no scheme: Authorization: <SERVICE_TOKEN_ID>:<SERVICE_TOKEN>. Older service tokens only work in this form. Sending the token on its own, without Bearer or the ID, returns 401. Most endpoints only need a service token for authentication, but some organization-specific endpoints also need OAuth. Each endpoint will state what types of authentication are allowed. See the Service tokens documentation for creating a service token and granting it permissions.

​
OAuth applications

All OAuth applications have a comprehensive list of scopes that the application can request from the PlanetScale user. See the OAuth documentation for more info.

​
Finding endpoints

The sidebar lists every endpoint, grouped by product. The same reference is available as one text file at https://planetscale.com/docs/_llms/api-reference.txt, and the OpenAPI specification is served at https://api.planetscale.com/v1/openapi-spec. See OpenAPI specification for details.

​
Waiting for new resources

Creating a database, branch, or backup returns before the resource is ready. Poll it until it is ready before you connect to it or use it: Each of these usually takes a few minutes. Poll every few seconds instead of in a tight loop.

​
Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.