alt tag Cloudant Basics

Important: All Cloudant documentation has moved to the IBM Bluemix platform. You can find the new content here, and the ‘Cloudant Basics’ topic in particular here.

Content on this page will no longer be updated (Jan 31st, 2017).

If it’s your first time here, scan this section before you scroll further. The sections on Client Libraries, API Reference, and Guides assume you know some basic things about Cloudant.


All requests to Cloudant go over the web, which means any system that can speak to the web, can speak to Cloudant. All language-specific libraries for Cloudant are really just wrappers that provide some convenience and linguistic niceties to help you work with a simple API. Many users even choose to use raw HTTP libraries for working with Cloudant.

Specific details about how Cloudant uses HTTP is provided in the HTTP topic of the API Reference.

Cloudant supports the following HTTP request methods:

If the client (such as some web browsers) does not support using these HTTP methods, POST can be used instead with the X-HTTP-Method-Override request header set to the actual HTTP method.

Method not allowed error

    "reason":"Only GET,HEAD allowed"

If you use an unsupported HTTP request type with a URL that does not support the specified type, a 405 error is returned, listing the supported HTTP methods, as shown in the example.


Cloudant stores documents using JSON (JavaScript Object Notation) encoding, so anything encoded into JSON can be stored as a document. Files like images, videos, and audio are called BLObs (binary large objects) and can be stored as attachments within documents.

More information about JSON can be found in the JSON Guide.

Distributed Systems

Cloudant’s API enables you to interact with a collaboration of numerous machines, called a cluster. The machines in a cluster must be in the same datacenter, but can be within different ‘pods’ in that datacenter. Using different pods helps improve the High Availability characteristics of Cloudant.

An advantage of clustering is that when you need more computing capacity, you just add more machines. This is often more cost-effective and fault-tolerant than scaling up or enhancing an existing single machine.

For more information about Cloudant and distributed system concepts, see the CAP Theorem guide.


Replication is a procedure followed by Cloudant, CouchDB, PouchDB, and others. It synchronizes the state of two databases so that their contents are identical.

You can continuously replicate. This means that a target database updates every time the source database changes. Testing for source changes involves ongoing internal calls. Continuous replication can be used for backups of data, aggregation across multiple databases, or for sharing data.