Get Started with the Data API

Capella Operational

how-to

To get started with the Couchbase Capella Data API, you must create a cluster access credential and enable the Data API for the cluster.

Introduction

To access the Data API, you must first enable the Data API for the cluster. Couchbase Capella provides a unique base URL which you can use to access the Data API for that cluster.

Cluster Access

A cluster access credential authenticates and authorizes you to access the Data API. You can use an existing cluster access credential, or create a new one. The access privileges that you specify for the cluster access credential determine the buckets, scopes, and collections that you can access via the Data API.

Private Networking

If you want to access the Data API over a VPC Peering connection, you must activate VPC Peering for the Data API when you enable the Data API itself. You must then set up VPC Peering in a separate step.

If you want to access the Data API through a private endpoint, do not activate VPC Peering for the Data API. Instead, enable the Data API, and set up a private endpoint for the Data API in a separate step.

IP Access over Public Network

To use the Data API over a public network, you must specify which IP addresses can access the Couchbase Capella cluster. For security, it’s recommended that clients should only be able to access the cluster from specific IP addresses.

For each cluster, you can grant access from:

Any IP address.
Individual IP addresses.
Blocks of IP addresses using CIDR notation.

Permitted IP addresses and address ranges must be in IPv4 format.

If you’re accessing the Data API via a VPC Peering connection or a private endpoint, you do not need to permit access from the peered range of private IP addresses.

Prerequisites

The procedures on this page assume the following:

You have configured cluster access by creating a cluster access credential. You’ll need the username and password for the cluster credential to connect to the Data API.
You have added your IP address to the cluster’s list of allowed IPs, if required.
You’re not connecting from an IPv6-only environment — you need to be able to use the IPv4 records published for Capella clusters.

You can do all of this from a single location using the Connect page in the Capella UI, or the Management API.

Examples on this Page

In the Management API examples on this page:

$organizationId is the organization ID.
$projectId is the project ID.
$clusterId is the cluster ID.
$apiKeySecret is the API key secret, used as the Bearer token.

The endpoints described on this page all have the same base path: /v4/organizations/{organizationId}/projects/{projectId}/clusters/{clusterId}. For clarity, this is not shown in the instructions, but it’s included in the examples.

For details, see Manage Deployments with the Management API.

Enable the Data API

You can enable the Data API using the Capella UI or the Management API.

Capella UI
Management API

On the Operational Clusters page, click on the cluster that you want to connect to.
Go to Connect Data API.
If necessary, follow the instructions on screen to enter an allowed IP address range.
If necessary, follow the instructions on screen to create a new cluster user.
Click Enable Data API. When prompted, type Yes and click Confirm.
Wait for Couchbase Capella to deploy the Data API. This may take several minutes.
When the Data API is deployed, copy the Data API Endpoint — this is the base URL you’ll need to connect to the cluster.
If required, select Enable Data API over VPC Peered Network. This will incur extra charges.
To get started with the Data API, choose a cluster user from the drop-down, and then copy the generated sample code. Replace <<password>> with the password you specified when you created the cluster access user.

If necessary, use POST /allowedcidrs to enter an allowed IP address range.

curl -X POST "https://cloudapi.cloud.couchbase.com/v4/organizations/$organizationId/projects/$projectId/clusters/$clusterId/allowedcidrs" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $apiKeySecret" \
  -d '{
  "cidr": "6.60.28.100/32",
  "comment": "Allows access from my local developer machine",
  "expiresAt": "2026-05-14T21:49:58.465Z"
}'

If necessary, use POST /users to create a cluster user.

curl -X POST "https://cloudapi.cloud.couchbase.com/v4/organizations/$organizationId/projects/$projectId/clusters/$clusterId/users" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $apiKeySecret" \
  -d '{
  "name": "WriteAccessForAllBuckets",
  "access": [
    {
      "privileges": [
        "data_writer"
      ]
    }
  ]
}'

Use PUT /dataAPI to enable the Data API, and optionally enable VPC peering for the Data API.
- To enable the Data API, pass "enableDataAPI": true in the request body.
- To enable VPC peering for the Data API, pass "enableNetworkPeering": true in the request body. This will incur extra charges.
```
curl -X PUT "https://cloudapi.cloud.couchbase.com/v4/organizations/$organizationId/projects/$projectId/clusters/$clusterId/dataAPI" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $apiKeySecret" \
  -d '{
  "enableDataApi": true,
  "enableNetworkPeering": true
}'
```

Use GET /dataAPI to check the status of the Data API. It may take several minutes to deploy the Data API.

curl -X GET "https://cloudapi.cloud.couchbase.com/v4/organizations/$organizationId/projects/$projectId/clusters/$clusterId/dataAPI" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $apiKeySecret"

Copy the connection string returned by GET /dataAPI — this is the base URL you’ll need to connect to the cluster.

Disable the Data API

You can disable the Data API using the Capella UI or the Management API.

Capella UI
Management API

On the Operational Clusters page, click on the cluster that you want to connect to.
Go to Connect Data API.
Click Disable Data API. When prompted, click Confirm.

Use PUT /dataAPI to disable VPC peering for the Data API, or disable the Data API altogether.

To disable VPC peering for the Data API, pass "enableNetworkPeering": false in the request body.
To disable the Data API altogether, pass "enableDataAPI": false in the request body.

curl -X PUT "https://cloudapi.cloud.couchbase.com/v4/organizations/$organizationId/projects/$projectId/clusters/$clusterId/dataAPI" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $apiKeySecret" \
  -d '{
  "enableDataApi": false,
  "enableNetworkPeering": false
}'

Use GET /dataAPI to check the status of the Data API.

curl -X GET "https://cloudapi.cloud.couchbase.com/v4/organizations/$organizationId/projects/$projectId/clusters/$clusterId/dataAPI" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $apiKeySecret"

Next Steps

To set up a private endpoint for the Data API, see Add Private Endpoints for the Data API.
To set up VPC peering, see Configure a VPC Peering Connection.
To make an API call, see Make an API Call with the Data API.
To understand when to use the Data API, see Data API vs. Couchbase SDKs.
For a full reference guide, see Data API Reference.