canonical: https://jentic.com/apis/cockroachlabs.cloud/cockroachdb-cloud

# Cockroachlabs CockroachDB Cloud API

The CockroachDB Cloud API manages every resource in a Cockroach Labs Cloud organisation - clusters, databases, SQL users, backups, network allow-lists, private endpoints, CMEK encryption keys, and audit log destinations - through a single Bearer-authenticated REST surface. It also exposes SCIM 2.0 user and group endpoints for identity federation with corporate IdPs. Created and maintained by Cockroach Labs themselves, the API is the underpinning for both the cockroachlabs.cloud console and the official Terraform provider.

## For AI agents

Provision and manage CockroachDB Cloud clusters, databases, SQL users, backups, and network rules across 144 endpoints from a single Bearer-authenticated API.

## Scope

Does not run SQL queries against your data, expose live cluster metrics, or replace the cockroach SQL client - use for CockroachDB Cloud control-plane management only.

## Capabilities

- Create, scale, upgrade, and delete CockroachDB clusters via `/api/v1/clusters` and `/api/v1/clusters/{cluster_id}`
- Create, list, update and delete databases inside a cluster via `/api/v1/clusters/{cluster_id}/databases` endpoints
- Configure cluster backup policy and list existing backups via `/api/v1/clusters/{cluster_id}/backups` and /backups-config
- Lock down access with network allow-lists, private endpoints, and Client CA certificates per cluster
- Enable customer-managed encryption keys (CMEK) on a cluster through the /cmek endpoints
- Federate users and groups via the SCIM 2.0 surface at `/api/scim/v2/Users` and `/api/scim/v2/Groups`

## Use cases

### Cluster Provisioning Automation

Provision CockroachDB Cloud clusters from CI/CD or platform self-service portals. POST `/api/v1/clusters` initialises a new cluster with the chosen plan and region, GET `/api/v1/clusters/available-regions` returns the region list, and PATCH on the cluster scales it as load grows. The same surface backs the official Terraform provider, so Day 0 setup typically takes under 20 minutes per environment.

Example prompt: Call POST `/api/v1/clusters` to create a serverless cluster named 'staging' in us-east1, then return the connection string from GET `/api/v1/clusters/{cluster_id}/connection-string.`

### Backup and Disaster Recovery

Configure and audit cluster backups across an organisation. GET `/api/v1/clusters/{cluster_id}/backups` lists existing backups, PATCH /backups-config updates retention policy, and a separate restore workflow runs from those backups. Useful for meeting RPO and RTO targets in a compliance review without manual ops effort.

Example prompt: Call PATCH `/api/v1/clusters/{cluster_id}/backups-config` to set retention to 30 days for cluster id abc-123.

### Security Posture and Network Lockdown

Enforce network and encryption policy across CockroachDB clusters. The /allowlist, /private-endpoints, /client-ca-cert, and /cmek endpoint groups let an automation add IP CIDRs, attach private connectivity, set client CA certificates, and enable customer-managed encryption keys on a per-cluster basis. This pattern is core to passing SOC 2 and HIPAA reviews.

Example prompt: Add the CIDR 10.0.0.0/16 to the allow-list of cluster id abc-123 by POSTing to the cluster's allowlist endpoint.

### Identity Federation via SCIM

Sync users and groups from an enterprise IdP using the SCIM 2.0 endpoints under `/api/scim/v2.` POST `/api/scim/v2/Users` provisions an identity, PATCH `/api/scim/v2/Users/{id}` applies updates, and DELETE deprovisions. The SCIM surface also covers groups, schemas, and a service-provider config endpoint so an IdP can run discovery automatically.

Example prompt: Call POST `/api/scim/v2/Users` with the new hire's profile and assign them to the 'engineers' group via PATCH `/api/scim/v2/Groups/{id}.`

### AI Agent Database Provisioning via Jentic

An AI platform engineer agent uses Jentic to create on-demand CockroachDB clusters for feature branches and tear them down on PR merge. The agent searches for 'create a CockroachDB cluster', loads the schema, and executes - Jentic supplies the Bearer API key from the vault so the agent never sees the credential.

Example prompt: Use Jentic to search for 'create a CockroachDB cluster', load the POST `/api/v1/clusters` schema, and create a serverless cluster for branch 'feature-x'.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/clusters` | Create and initialise a new cluster |
| GET | `/api/v1/clusters` | List clusters in the organisation |
| PATCH | `/api/v1/clusters/{cluster_id}` | Scale, edit, or upgrade a cluster |
| GET | `/api/v1/clusters/{cluster_id}/connection-string` | Get the connection string for a cluster |
| GET | `/api/v1/clusters/{cluster_id}/backups` | List cluster backups |
| POST | `/api/v1/clusters/{cluster_id}/cmek` | Enable CMEK on a cluster |
| GET | `/api/v1/auditlogevents` | List audit log events |
| POST | `/api/scim/v2/Users` | Create a SCIM user |

## Key resources

- **Clusters** — Create, list, update, delete, and inspect CockroachDB Cloud clusters
- **Databases and SQL Users** — Manage databases and SQL users inside a cluster
- **Backups** — List backups and configure backup policy per cluster
- **Network and Security** — Allow-lists, private endpoints, Client CA certs, and CMEK keys
- **API Keys** — Issue and revoke API keys for the organisation
- **Audit Logs** — Read audit events for the organisation
- **SCIM 2.0** — Provision and deprovision users and groups via SCIM

## Why Jentic

- **Setup:** Wiring the CockroachDB Cloud API by hand means learning its bearer auth, targeting cockroachlabs.cloud, and handling paging and retries across a large control-plane surface yourself. Through Jentic you install once, import the CockroachDB Cloud API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** CockroachDB Cloud puts the cluster id in the URL path (`/api/v1/clusters/{cluster_id}/...`), so a rule can pin your agent to one cluster for reads like its connection string and backups. You choose the operations it may call, so ones that change state like editing a cluster or provisioning CMEK are not included unless you add them.
- **Credential handling:** Your CockroachDB Cloud API key is stored once, encrypted, by your own Jentic One instance and added to the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a CockroachDB cluster' or 'add an IP allow-list entry', and Jentic returns the matching CockroachDB Cloud operation with its parameter schema so the agent calls the right endpoint without scanning the full reference.

## Related APIs

- **MongoDB Atlas** — MongoDB Atlas exposes a similar control-plane API for MongoDB clusters.
- **PlanetScale** — PlanetScale provides a managed Vitess-based MySQL-compatible service.
- **Neon** — Neon offers serverless PostgreSQL with branching for development.
- **DigitalOcean** — DigitalOcean hosts the application compute that connects to CockroachDB Cloud.

## FAQ

### What authentication does the CockroachDB Cloud API use?

The API uses HTTP Bearer authentication. Generate an API key in the Cockroach Labs Cloud console at https://cockroachlabs.cloud and pass it in the Authorization header on every request. Through Jentic the API key is stored encrypted in the vault and injected at execution time.

### Can I create and scale CockroachDB clusters with this API?

Yes. POST `/api/v1/clusters` creates a cluster with the chosen plan and region, PATCH `/api/v1/clusters/{cluster_id}` scales or edits it (including version upgrades), and DELETE on the same path tears it down. The same operations back the official Terraform provider.

### What are the rate limits for the CockroachDB Cloud API?

The OpenAPI spec does not declare numeric rate limits. Cockroach Labs applies tenant-level throttling, particularly on cluster creation, so platform automations should serialise create/delete loops and back off on 429 responses.

### How do I retrieve a connection string for a cluster through Jentic?

Search Jentic for 'CockroachDB connection string', load the GET `/api/v1/clusters/{cluster_id}/connection-string` schema, and execute with the cluster id. Install the SDK with pip install jentic and call it via the async client. The endpoint returns a generic, region-agnostic connection string.

### Does the API support SCIM provisioning?

Yes. The `/api/scim/v2` surface implements SCIM 2.0 - Users, Groups, ResourceTypes, Schemas, and ServiceProviderConfig - so an enterprise IdP such as Okta or Entra ID can provision and deprovision Cockroach Cloud users and groups automatically.

### Can I manage backups and CMEK encryption through the API?

Yes. `/api/v1/clusters/{cluster_id}/backups` lists backups, /backups-config configures retention, and the /cmek endpoint group enables and rotates customer-managed encryption keys on a per-cluster basis. These cover the typical SOC 2 and HIPAA control points for managed databases.

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

Yes. Because you run Jentic One yourself, your own rules decide which CockroachDB Cloud operations and credentials the agent can use. Since the cluster id sits in the URL path (`/api/v1/clusters/{cluster_id}/...`), you can pin the agent to a single cluster and to read-only calls such as fetching its connection string or listing backups. State-changing operations like editing a cluster or provisioning CMEK stay off limits unless you explicitly add them.