canonical: https://jentic.com/apis/couchbase.com/couchbase

# Couchbase Capella Management API

Jentic publishes the only available OpenAPI specification for Couchbase Capella Management API, keeping it validated and agent-ready. The Couchbase Capella Management API is the v4 control plane for Couchbase's managed NoSQL database service, exposing 259 endpoints to provision and manage clusters, projects, buckets, scopes, collections, app services, backup schedules, audit logs, CIDR allowlists, API keys, and customer-managed encryption keys (CMEK). It also covers AI workflows, app endpoints, and on/off schedules so teams can fully automate the lifecycle of a Capella deployment from CI.

## For AI agents

Provision and manage Couchbase Capella clusters, projects, buckets, app services, backups, and access controls through the Capella v4 management API. Bearer-token authentication with 259 endpoints scoped to organisation, project, and cluster.

## Scope

Does not handle in-cluster data operations (KV gets, N1QL queries) or self-managed Couchbase Server admin - use for Capella control-plane management of clusters, projects, buckets, App Services, and access controls only.

## Capabilities

- Create and tear down free-tier and standard Capella clusters under a project, including on/off schedules to manage cost
- Manage projects, organisation API keys, and key rotation for fine-grained access control
- Configure buckets, scopes, and collections plus their backup and restore schedules to keep data durable
- Operate app services - endpoints, audit logging, log streaming, and private endpoints - for the mobile sync surface
- Enforce network isolation through allowed CIDRs at both cluster and app-service level
- Set up customer-managed encryption keys (CMEK) on AWS, Azure, and GCP for compliance-driven workloads
- Trigger AI workflow runs and inspect AI service provider configurations linked to a Capella project

## Use cases

### Ephemeral Dev/Test Capella Clusters

Spin up Capella clusters at the start of an integration test job and tear them down when the job completes, scoped to the project that owns the test fixtures. The on/off schedule endpoints let teams park clusters overnight to keep costs predictable, and the free-tier cluster operations support quick demo environments.

Example prompt: On test start call POST `/v4/organizations/{organizationId}/projects/{projectId}/clusters`, run tests, then DELETE the cluster - or use POST `/v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}/onOffSchedule` to park it overnight.

### Compliance-Ready Bucket and Encryption Setup

When a regulated workload comes online, configure customer-managed encryption keys on the cloud provider, attach them to the Capella project, and then create the bucket with the correct backup schedule. Audit logging on the cluster ensures every change is captured for review.

Example prompt: Call POST `/v4/organizations/{organizationId}/cmek` to register the key, POST the bucket on the cluster, and PUT the audit log configuration to enable change capture.

### Sync-Gateway-Style App Services Operations

Run the mobile sync surface (App Services) end-to-end: register endpoints, configure audit logging, stream logs to the team's observability stack, and lock down access with allowed CIDRs and private endpoints. Each subsystem has dedicated endpoints, so an operator can build a single playbook to roll out App Services across new clusters.

Example prompt: Call the App Endpoints, App Services Audit Logging, App Services Log Streaming, and App Services Private Endpoints endpoint groups under `/v4/organizations/{organizationId}/projects/{projectId}` to configure the surface for a cluster.

### AI Agent Couchbase SRE Assistant via Jentic

An SRE agent answers questions like 'turn off the dev cluster every weekend' or 'rotate the production API key' by routing each request to the right Capella v4 operation through Jentic. The agent reasons over capabilities and Jentic returns the right operation schema rather than the agent juggling 259 endpoints.

Example prompt: Search Jentic for 'create Capella cluster on/off schedule' or 'rotate Capella API key', load the matching operation, and execute it with the organisation, project, and cluster IDs.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v4/organizations/{organizationId}/projects` | Create a project |
| POST | `/v4/organizations/{organizationId}/projects/{projectId}/clusters` | Create a cluster |
| GET | `/v4/organizations/{organizationId}/projects/{projectId}/clusters` | List clusters in a project |
| POST | `/v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}/onOffSchedule` | Create cluster on/off schedule |
| POST | `/v4/organizations/{organizationId}/apikeys` | Create an organisation API key |
| POST | `/v4/organizations/{organizationId}/apikeys/{ApiKeyId}/rotate` | Rotate an organisation API key |
| GET | `/v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}/stats` | Get cluster capacity stats |
| POST | `/v4/organizations/{organizationId}/cmek` | Register CMEK key metadata |

## Key resources

- **Organisations and Projects** — Org-level cloud accounts, projects, and API keys with rotation.
- **Clusters** — Standard and free-tier clusters with on/off schedules, capacity stats, and audit logging.
- **Buckets, Scopes, Collections** — Data containers and their backup/restore and snapshot schedules.
- **App Services** — Endpoints, audit logging, log streaming, allowed CIDRs, and private endpoints for the mobile sync surface.
- **Network and CMEK** — Allowed CIDRs, certificates, and customer-managed encryption keys on AWS, Azure, and GCP.
- **AI Services and Workflows** — AI service providers and AI workflows linked to a Capella project.
- **Backups and Snapshots** — Bucket backup schedule, restore, and cloud snapshot operations.

## Why Jentic

- **Setup:** Wiring the Couchbase Capella Management API by hand means learning its bearer auth, pinning the cloudapi.cloud.couchbase.com control-plane host, and coding your own requests across a large organization, project, and cluster hierarchy. Through Jentic you install once, import the Capella Management API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Capella nests the organization, project, and cluster ids in the URL path (`/v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}/...`), so a rule can pin your agent to one project or cluster: it acts only within that scope. You choose the operations it may call, so control-plane changes like rotating an API key or creating a cluster are not included unless you add them.
- **Credential handling:** Your Capella 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 'list clusters in a project' or 'read cluster stats', and Jentic returns the matching Capella operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **MongoDB Atlas API** — Managed document database with similar control-plane scope across clusters, projects, and access management.
- **Cockroach Cloud API** — Managed distributed SQL database control plane.
- **Redis Cloud API** — Managed Redis service that pairs with Capella for low-latency cache in front of the document store.

## FAQ

### Why is there no official OpenAPI spec for Couchbase Capella Management API?

Couchbase publishes Capella documentation but not a single OpenAPI specification covering the v4 management surface. Jentic generates and maintains this spec so that AI agents and developers can call Couchbase Capella Management API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Couchbase Capella Management API use?

The API uses HTTP bearer-token authentication backed by an organisation API key created from the Capella console or from POST `/v4/organizations/{organizationId}/apikeys.` Through Jentic the key is held in the encrypted vault and injected into the Authorization header at execution time.

### Can I create and turn off clusters on a schedule?

Yes. POST `/v4/organizations/{organizationId}/projects/{projectId}/clusters` creates a cluster, and POST `/v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}/onOffSchedule` installs an on/off schedule that pauses the cluster outside working hours to control cost.

### Does the API support customer-managed encryption keys?

Yes. The CMEK endpoint group lets you register key metadata at the organisation or project level for AWS, Azure, and GCP and attach those keys to clusters, which is the canonical primitive for compliance-driven workloads.

### What are the rate limits for the Capella Management API?

The OpenAPI spec does not declare numeric rate limits. Treat HTTP 429 responses as authoritative, back off using the Retry-After header where present, and consult Couchbase docs for the limits that apply to your organisation tier before high-frequency operations.

### How do I provision a free-tier cluster through Jentic?

Search Jentic for 'create Capella free tier cluster', load POST `/v4/organizations/{organizationId}/projects/{projectId}/clusters/freeTier`, and execute it with the organisation and project IDs and the cluster definition. Jentic returns the operation schema so the agent does not need to hand-craft the JSON body.

### Can I limit what my agent is allowed to do with the Couchbase Capella Management API?

Yes. Because you run Jentic One yourself, your own rules decide which Capella operations and credentials the agent may use. Since Capella nests the organization, project, and cluster IDs in the URL path (for example `/v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}`), a rule can pin the agent to a single project or cluster so it acts only within that scope. You also pick the exact operations it may call, so read-only actions like listing clusters or reading cluster stats can be permitted while control-plane changes such as creating a cluster or rotating an organisation API key stay off-limits unless you add them.