canonical: https://jentic.com/apis/planetscale.com/planetscale-api

# PlanetScale API

PlanetScale is a serverless MySQL platform built on Vitess, the horizontal scaling system that powers YouTube and Slack. The PlanetScale API provides comprehensive control over database lifecycle management, branching workflows, backup policies, deployment requests, and organization administration. Developers use it to automate database provisioning in CI/CD pipelines, implement schema change workflows with branch-based development, manage connection credentials programmatically, and monitor query performance through insights endpoints. The API supports multi-region deployments, automatic sharding, and zero-downtime schema migrations. It enables infrastructure-as-code patterns for database management, allowing teams to version database schemas alongside application code and execute deploy requests that safely apply changes to production branches.

## For AI agents

Manage PlanetScale serverless MySQL databases including branching, schema migrations, backups, deploy requests, and organization settings.

## Scope

Provides database lifecycle management and schema migration orchestration. Does not execute queries against database branches-use MySQL connection strings for application data access. Does not provide query optimization or index tuning-use PlanetScale Insights dashboard.

## Capabilities

- Create and manage database branches for development, staging, and production environments
- Execute deploy requests to apply schema changes with automatic conflict detection
- Configure backup policies with retention periods and automated schedules
- Manage database passwords and connection strings programmatically
- Monitor query insights including slow queries and connection pool metrics
- Administer organization members, teams, and service tokens with role-based access control
- Configure regional database deployments and cluster sizing for performance tuning

## Use cases

### Branch-Based Schema Development Workflow

Development teams use PlanetScale's branching model to develop database schema changes in isolation, similar to Git workflows. The API allows creating feature branches from production, applying migrations to the branch, running integration tests against the branch database, and then submitting a deploy request. Automated CI pipelines use the API to create ephemeral branches for each pull request, enabling schema change review and testing before merging to production. This eliminates the risk of breaking changes and enables true database versioning alongside application code.

Example prompt: Create a new PlanetScale branch from production, apply schema migration SQL to the branch, wait for safe migrations to complete, create a deploy request to merge changes back to production.

### Automated Infrastructure Provisioning

Platform engineering teams use the API to provision databases as part of application deployment workflows. Terraform providers and custom automation tools call the API to create databases, configure cluster sizes for expected load, set up backup policies, generate connection credentials, and inject them into application environments. This enables self-service database provisioning for developers while maintaining governance through organization-level policies. Each microservice or tenant can receive its own isolated database with standardized configuration.

Example prompt: Create a new database in PlanetScale organization, configure cluster size for production workload, create initial main branch, generate connection password, and return connection string for application configuration.

### Zero-Downtime Schema Migration Orchestration

SRE teams orchestrate complex schema migrations using deploy requests that PlanetScale executes with zero downtime. The API enables creating a deploy request between branches, monitoring its status as PlanetScale validates the migration safety, and tracking the deployment progress. For changes PlanetScale cannot safely auto-deploy (like dropping columns with data), the API provides deployment instructions and allows manual approval workflows. This reduces risk for high-traffic databases where traditional migration tools cause seconds or minutes of downtime.

Example prompt: Create deploy request to merge schema changes from staging branch to production, poll deploy request status, check for migration warnings, and monitor deployment progress until schema change is live.

### Database Backup and Disaster Recovery Automation

Infrastructure teams use the API to manage backup policies ensuring compliance with RTO/RPO requirements. The API configures automated backup schedules, sets retention periods based on regulatory needs, and provides endpoints to list available backup snapshots. In disaster scenarios, the API allows restoring databases from specific backup points, creating new branches from backup snapshots for forensic analysis, and auditing backup history. This enables automated disaster recovery runbooks that can restore service with minimal manual intervention.

Example prompt: Configure backup policy for production database with 30-day retention, verify automated backups are running on schedule, list available backup snapshots, and test restore process by creating new branch from backup.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/organizations/{organization}/databases` | Create a new database |
| GET | `/organizations/{organization}/databases/{database}/branches` | List branches for a database |
| POST | `/organizations/{organization}/databases/{database}/branches/{branch}/deploy-requests` | Create a deploy request to merge schema changes |
| GET | `/organizations/{organization}/databases/{database}/branches/{branch}/passwords` | List passwords for a database branch |
| POST | `/organizations/{organization}/databases/{database}/branches/{branch}/passwords` | Create a new database password |

## Key resources

- **Databases** — Create, list, and manage PlanetScale databases within an organization.
- **Branches** — Manage database branches for development, staging, and production environments.
- **Deploy Requests** — Create and manage schema migration requests between branches.
- **Passwords** — Generate and manage database connection credentials.
- **Backup Policies** — Configure automated backup schedules and retention settings.

## Why Jentic

- **Setup:** Wiring the PlanetScale API by hand means setting up its OAuth service-token auth and hand-building requests across its database, branch, deploy-request and password endpoints yourself. Through Jentic you install once, import PlanetScale from the API Directory, store the service token once, and your agent calls it.
- **Permission scoping:** PlanetScale puts the organization, database and branch in the URL path (`/organizations/{organization}/databases/{database}/branches/{branch}/...`), so a rule can pin your agent to one organization or database: it manages branches and deploy requests there and nothing else. You choose the operations it may call, so ones like creating branch passwords are not included unless you add them.
- **Credential handling:** Your PlanetScale service token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a database branch for schema testing' or 'open a deploy request', and Jentic returns the matching PlanetScale operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Neon API** — Neon provides serverless Postgres with branching similar to PlanetScale's approach for MySQL.
- **Supabase Management API** — Supabase provides managed Postgres with APIs for database provisioning and real-time subscriptions.

## FAQ

### What authentication does the PlanetScale API use?

The PlanetScale API uses OAuth 2.0 service tokens for authentication. You generate service tokens in the PlanetScale dashboard with organization or database-level permissions, then pass the token in the Authorization header as a Bearer token.

### How does PlanetScale branching differ from traditional database environments?

PlanetScale branches are isolated database instances that share the same schema lineage. Unlike traditional staging databases that drift from production, branches track schema changes and enable merge-based deployments with conflict detection, similar to Git workflows.

### What is a deploy request in PlanetScale?

A deploy request is a schema migration proposal that merges changes from one branch to another. PlanetScale analyzes the migration for safety, executes it with zero downtime when possible, and provides manual deployment instructions for changes requiring careful coordination.

### Can I automate database provisioning in CI/CD with the PlanetScale API?

Yes. The API provides full lifecycle management including database creation, branch provisioning, password generation, and connection string retrieval. Many teams use it with Terraform, GitHub Actions, or custom automation to provision databases per pull request or environment.

### How do AI agents use the PlanetScale API through Jentic?

Agents search Jentic for tasks like 'create a database branch for testing' and receive the PlanetScale API operation schemas. Jentic securely stores the service token and handles authentication, allowing agents to execute branching, migration, and provisioning workflows with natural language parameters.

### Can I limit what my agent is allowed to do with the PlanetScale API?

Yes. Because you self-host Jentic One, your own rules decide which PlanetScale operations and credentials the agent may use. Since PlanetScale puts the organization, database, and branch in the URL path, a rule can pin the agent to a single organization or database so it only manages branches and deploy requests there. You also pick the exact operations it can call, so sensitive ones like creating branch passwords stay out of reach unless you add them.