A newer version of this documentation is available.

View Latest

REST API reference

      The Couchbase Server REST API enables you to manage a Couchbase Server deployment as well as perform operations such as storing design documents and querying for results.

      Use the REST API to manage clusters, server nodes, and buckets, and to retrieve run-time statistics within a Couchbase Server deployment.


      When developing a Couchbase Server-compatible SDK, the REST API is used within your library to handle views. Views enable you to index and query data based on functions that you define.

      The REST API should not be used to read or write data to the server. Data operations, such as set and get are handled by Couchbase Server SDKs. Using the REST API for CRUD does not scale as well as SDKs and does not offer the same level of data protection.

      In addition, the Couchbase Web Console uses REST API endpoints for administrative tasks, such as creating a new bucket, adding a node to a cluster, or changing cluster settings.

      Build your request starting from Couchbase Server cluster URIs. Be aware that URIs for resources may change from version to version. The URI hierarchies facilitate reuse of requests because they follow a similar pattern for accessing different parts of the system.

      Types of resources

      There are a number of different resources within the Couchbase Server and these resources require a different URI/RESTful-endpoint in order to perform operations:

      Server nodes

      A Couchbase Server instance, also known as a server or server node, is a physical or virtual machine running Couchbase Server. Each server node is a member of a cluster.


      A cluster is a group of one or more servers and is a collection of physical resources that are grouped together and provide services and a management interface. A single default cluster exists for every deployment of Couchbase Server. A server node, or instance of Couchbase Server, is a member of a cluster. Couchbase Server collects run-time statistics for clusters, maintaining an overall pool-level data view of counters and periodic metrics of the overall system. The Couchbase Server REST API can be used to retrieve historic statistics for a cluster.


      A bucket is a logical grouping of data within a cluster. It provides a name space for all the related data in an application. You can use the same key in two different buckets and they are treated as unique items by Couchbase Server.

      Couchbase Server collects run-time statistics for buckets, maintaining an overall bucket-level data view of counters and periodic metrics of the system. Buckets are categorized by storage type. Memcached buckets are for in-memory, RAM-based information. Couchbase buckets are for persisted data.


      Views enable you to index and query data based on logic you specify. You can also use views to perform calculations and aggregations, such as statistics, for items in Couchbase Server.

      Cross Datacenter Replication (XDCR)

      Cross Datacenter Replication (XDCR) enables automatic replication of data between clusters and between data buckets. The major benefits include the ability to restore data from one Couchbase Server cluster to another cluster after system failure and the ability to provide copies of data on clusters that are physically closer to end users.

      HTTP request headers

      The following HTTP request headers are used to create requests:

      Header Supported Values Description of Use Required


      Comma-delimited list of media types or media type patterns.

      Indicates to the server what media type(s) this client is prepared to accept.



      Basic plus username and password (per RFC 2617).

      Identifies the authorized user making this request.

      No, unless secured


      Body Length (in bytes)

      Describes the size of the message body.

      Yes, on requests that contain a message body.


      Content type

      Describes the representation and syntax of the request message body.

      Yes, on requests that contain a message body.


      Origin host name

      Required to allow support of multiple origin hosts at a single IP address.

      All requests



      Declares the specification version of the YYYYY API that this client was programmed against.


      HTTP response codes

      The Couchbase Server returns one of the following HTTP status codes in response to REST API requests:

      HTTP response Description

      200 OK

      Successful request and an HTTP response body returns. If this creates a new resource with a URI, the 200 status will also have a location header containing the canonical URI for the newly created resource.

      201 Created

      Request to create a new resource is successful, but no HTTP response body returns. The URI for the newly created resource returns with the status code.

      202 Accepted

      The request is accepted for processing, but processing is not complete. Per HTTP/1.1, the response, if any, SHOULD include an indication of the request’s current status, and either a pointer to a status monitor or some estimate of when the request will be fulfilled.

      204 No Content

      The server fulfilled the request, but does not need to return a response body.

      400 Bad Request

      The request could not be processed because it contains missing or invalid information, such as validation error on an input field, a missing required value, and so on.

      401 Unauthorized

      The credentials provided with this request are missing or invalid.

      403 Forbidden

      The server recognized the given credentials, but you do not possess proper access to perform this request.

      404 Not Found

      URI provided in a request does not exist.

      405 Method Not Allowed

      The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this URI.

      406 Not Acceptable

      The resource identified by this request cannot create a response corresponding to one of the media types in the Accept header of the request.

      409 Conflict

      A create or update request could not be completed, because it would cause a conflict in the current state of the resources supported by the server. For example, an attempt to create a new resource with a unique identifier already assigned to some existing resource.

      500 Internal Server Error

      The server encountered an unexpected condition which prevented it from fulfilling the request.

      501 Not Implemented

      The server does not currently support the functionality required to fulfill the request.

      503 Service Unavailable

      The server is currently unable to handle the request due to temporary overloading or maintenance of the server.