Retrieve server instance information

GET /

When you access the root of an instance, IBM Cloudant returns meta-information about the instance. The response includes a JSON structure that contains information about the server, including a welcome message and the server's version.

Tip: The authentication for this endpoint is only enforced when using IAM.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.account-meta-info.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve list of running tasks

GET /_active_tasks

Lists running tasks, including the task type, name, status, and process ID. The result includes a JSON array of the currently running tasks, with each task described as a single object. Depending on the operation type, the set of response object fields might be different.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.account-active-tasks.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.account-active-tasks.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Query a list of all database names in the instance

GET /_all_dbs

Query to retrieve a list of database names from the instance.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.account-all-dbs.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.account-all-dbs.read

Request

Path Parameters

Query Parameters

descending

boolean

Query parameter to specify whether to return rows in descending by key order.

end_key

string

Query parameter to specify to stop returning records when the specified key is reached. String representation of any JSON type that matches the key type emitted by the view function.

limit

integer

Query parameter to specify the number of returned documents to limit the result to.

skip

integer

Query parameter to specify the number of records before starting to return the results.

start_key

string

Query parameter to specify to start returning records from the specified key. String representation of any JSON type that matches the key type emitted by the view function.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Query information about multiple databases

POST /_dbs_info

This operation enables you to request information about multiple databases in a single request, instead of issuing multiple `GET /{db}` requests. It returns a list that contains an information object for each database specified in the request.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.account-dbs-info.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.account-dbs-info.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Retrieve cluster membership information

GET /_membership

Displays the nodes that are part of the cluster as `cluster_nodes`. The field, `all_nodes`, displays all nodes this node knows about, including the ones that are part of the cluster. This endpoint is useful when you set up a cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.cluster-membership.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.cluster-membership.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Create a transient replication

POST /_replicate

Requests, configures, or stops a replicate operation. Note: Use the `_replicator` database to persist the replication configuration. That usage is preferred over this `/_replicate` endpoint, which is a transient operation.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication.write

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Create a persistent replication with a generated ID

POST /_replicator

Creates or modifies a document in the `_replicator` database to start a new replication or to edit an existing replication.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication.write

Request

Request Body

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Cancel a persistent replication

DELETE /_replicator/{doc_id}

Cancels a replication by deleting the document that describes it from the `_replicator` database.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication.write

Request

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

rev

Query parameter to specify a document revision.

Response

200 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve the configuration for a persistent replication

GET /_replicator/{doc_id}

Retrieves a replication document from the `_replicator` database to view the configuration of the replication. The status of the replication is no longer recorded in the document but can be checked via the replication scheduler.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication.read

Request

Path Parameters

Query Parameters

attachments

boolean

Query parameter to specify whether to include attachment content in the response. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.

att_encoding_info

boolean

Query parameter to specify whether to include the encoding information for compressed attachments. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.

atts_since

array

Query parameter to specify whether to include attachments only since specified revisions. Note this does not include the attachments for the specified revisions.

conflicts

boolean

Query parameter to specify whether to include a list of conflicted revisions in each returned document. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.

deleted_conflicts

boolean

Query parameter to specify whether to include a list of deleted conflicted revisions in the `_deleted_conflicts` property of the returned document.

latest

boolean

Query parameter to specify whether to force retrieving latest leaf revision, no matter what rev was requested.

local_seq

boolean

Query parameter to specify whether to include the last update sequence for the document.

open_revs

array

Query parameter to specify leaf revisions to retrieve. Additionally, it accepts a value of `all` to return all leaf revisions.

rev

Query parameter to specify a document revision.

revs

boolean

Query parameter to specify whether to include a list of all known document revisions.

revs_info

boolean

Query parameter to specify whether to includes detailed information for all known document revisions.

Response

200 -

304 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve the HTTP headers for a persistent replication

HEAD /_replicator/{doc_id}

Retrieves the HTTP headers containing minimal amount of information about the specified replication document from the `_replicator` database. The method supports the same query arguments as the `GET /_replicator/{doc_id}` method, but only headers like content length and the revision (ETag header) are returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication.read

Request

Path Parameters

Query Parameters

Response

200 -

304 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Create or modify a persistent replication

PUT /_replicator/{doc_id}

Creates or modifies a document in the `_replicator` database to start a new replication or to edit an existing replication.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication.write

Request

Request Body

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

new_edits

boolean

Query parameter to specify whether to prevent insertion of conflicting document revisions. If false, a well-formed _rev must be included in the document. False is used by the replicator to insert documents into the target database even if that leads to the creation of conflicts.

Avoid using this parameter, since this option applies document revisions without checking for conflicts, so it is very easy to accidentally end up with a large number of conflicts.

rev

Query parameter to specify a document revision.

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

412 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Retrieve replication scheduler documents

GET /_scheduler/docs

Lists replication documents, including information about all documents, even the ones in a completed or failed state. For each document, the endpoint returns the document ID, database, replication ID, source and target, and other information.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication-scheduler.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication-scheduler.read

Request

Path Parameters

Query Parameters

limit

integer

Query parameter to specify the number of returned documents to limit the result to.

skip

integer

Query parameter to specify the number of records before starting to return the results.

states

array

Query parameter to include only replication documents in the specified states. String must be a comma-delimited string.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve a replication scheduler document

GET /_scheduler/docs/_replicator/{doc_id}

Retrieves information about a replication document from the replicator database. The endpoint returns the document ID, database, replication ID, source and target, and other information.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication-scheduler.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication-scheduler.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve HTTP headers for a replication scheduler document

HEAD /_scheduler/docs/_replicator/{doc_id}

Retrieves the HTTP headers containing minimal amount of information about the specified replication scheduler document. Since the response body is empty, using the HEAD method is a lightweight way to check if the replication scheduler document exists or not.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication-scheduler.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication-scheduler.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve replication scheduler jobs

GET /_scheduler/jobs

Retrieves information about replications that were created via `/_replicate` endpoint, as well as those created from replication documents. It doesn't include replications that completed or failed to start because replication documents were malformed. Each job description includes source and target information, replication ID, history of recent events, and other information.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication-scheduler.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication-scheduler.read

Request

Path Parameters

Query Parameters

limit

integer

Query parameter to specify the number of returned jobs to limit the result to.

skip

integer

Query parameter to specify the number of records before starting to return the results.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve a replication scheduler job

GET /_scheduler/jobs/{job_id}

Retrieves the state of a single replication task based on its replication ID

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication-scheduler.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication-scheduler.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve the HTTP headers for a replication scheduler job

HEAD /_scheduler/jobs/{job_id}

Returns the HTTP headers that contain a minimal amount of information about the specified replication task. Only the header information is returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.replication-scheduler.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.replication-scheduler.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Query tokenization of sample text (GET)

GET /_search_analyze

Returns the results of analyzer tokenization of the provided sample text. This endpoint can be used for testing analyzer tokenization.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.account-search-analyze.execute

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.account-search-analyze.execute

Request

Path Parameters

Query Parameters

analyzer

Required *

Query parameter to specify search analyzer type.

text

Required *

Query parameter to specify search analyzer text.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Query tokenization of sample text

POST /_search_analyze

Returns the results of analyzer tokenization of the provided sample text. This endpoint can be used for testing analyzer tokenization.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.account-search-analyze.execute

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.account-search-analyze.execute

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Retrieve information about whether the server is up

GET /_up

Confirms that the server is up, running, and ready to respond to requests. If the cluster is unavailable the endpoint returns a `503` response code.

Tip: The authentication for this endpoint is only enforced when using IAM.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.account-up.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve HTTP headers about whether the server is up

HEAD /_up

Retrieves the HTTP headers about whether the server is up.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.account-up.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.account-up.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve one or more UUIDs

GET /_uuids

Requests one or more Universally Unique Identifiers (UUIDs) from the instance. The response is a JSON object that provides a list of UUIDs.

Tip: The authentication for this endpoint is only enforced when using IAM.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.cluster-uuids.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.cluster-uuids.read

Request

Path Parameters

Query Parameters

count

integer

Query parameter to specify the number of UUIDs to return.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Delete a database

DELETE /{db}

Deletes the specified database and all documents and attachments contained within it. To avoid deleting a database, the server responds with a 400 HTTP status code when the request URL includes a `?rev=` parameter. This response suggests that a user wanted to delete a document but forgot to add the document ID to the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.database.delete

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.database.delete

Request

Path Parameters

Query Parameters

Response

200 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve information about a database

GET /{db}

Retrieve detailed information about the database.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.database-info.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.database-info.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve the HTTP headers for a database

HEAD /{db}

Returns the HTTP headers that contain a minimal amount of information about the specified database. Since the response body is empty, using the HEAD method is a lightweight way to check if the database exists or not.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.database-info.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.database-info.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Create or modify a document in a database

POST /{db}

Creates or modifies a document in the specified database by using the supplied JSON document.

For creation, you may specify the document ID but you should not specify the revision. If you don't specify the document ID, then the server generates an ID for your document.

For modification, you must specify the document ID and a revision identifier in the JSON document.

If your document ID includes the `_local/` or `_design/` prefix, then this operation creates or modifies a local or a design document respectively.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.data-document.write
cloudantnosqldb.design-document.write
cloudantnosqldb.local-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.data-document.write
cloudantnosqldb.design-document.write
cloudantnosqldb.local-document.write

Request

Request Body

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

507 -

Create a database

PUT /{db}

Create a new database with the requested properties.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.database.create

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.database.create

Request

Path Parameters

Query Parameters

partitioned

boolean

Query parameter to specify whether to enable database partitions when creating a database.

Before using read the FAQs to understand the limitations and appropriate use cases.

n

The number of replicas of the database in the cluster. The default is 3, unless overridden in the `cluster config`.

q

The number of shards in the database. Each shard is a partition of the hash value range. Cloudant recommends using the default value for most databases. However, if your database is expected to be larger than 250 GB or have a lot of indexes, you may need to adjust the settings. In these cases, it's best to reach out to IBM Cloudant customer support for guidance on how to meet your specific needs and requirements.

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

412 -

415 -

429 -

500 -

502 -

503 -

504 -

Query a list of all documents in a database (GET)

GET /{db}/_all_docs

Queries the primary index (all document IDs). The results that match the query parameters are returned in a JSON object, including a list of matching documents with basic contents, such as the ID and revision. When no query parameters are specified, results for all documents in the database are returned. Optionally, document content or additional metadata can be included in the response.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

conflicts

boolean

descending

boolean

Query parameter to specify whether to return rows in descending by key order.

end_key

string

Query parameter to specify to stop returning records when the specified key is reached. String representation of any JSON type that matches the key type emitted by the view function.

end_key_doc_id

string

Query parameter to stop returning rows at the specified document ID. No effect if using `group` or not providing end key.

include_docs

boolean

Query parameter to specify whether to include the full content of the documents in the response.

inclusive_end

boolean

Query parameter to specify whether the specified end key should be included in the result.

key

string

Query parameter to specify to return only rows that match the specified key. String representation of any JSON type that matches the key type emitted by the view function.

keys

string

Query parameter to specify returning only rows that match any of the specified keys. String representation of a JSON array of keys that match the key type emitted by the view function. Must be URL encoded.

limit

integer

Query parameter to specify the number of returned documents to limit the result to.

skip

integer

Query parameter to specify the number of records before starting to return the results.

start_key

string

Query parameter to specify to start returning records from the specified key. String representation of any JSON type that matches the key type emitted by the view function.

start_key_doc_id

string

Query parameter to start returning rows at the specified document ID. No effect if using `group` or not providing start key.

update_seq

boolean

Query parameter to specify whether to include in the response an update_seq value indicating the sequence id of the database the view reflects.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Query a list of all documents in a database

POST /{db}/_all_docs

Queries the primary index (all document IDs). The results that match the request body parameters are returned in a JSON object, including a list of matching documents with basic contents, such as the ID and revision. When no request body parameters are specified, results for all documents in the database are returned. Optionally, document content or additional metadata can be included in the response.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Multi-query the list of all documents in a database

POST /{db}/_all_docs/queries

Runs multiple queries using the primary index (all document IDs). Returns a JSON object that contains a list of result objects, one for each query, with a structure equivalent to that of a single `_all_docs` request. This enables you to request multiple queries in a single request, in place of multiple `POST /{db}/_all_docs` requests.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Bulk modify multiple documents in a database

POST /{db}/_bulk_docs

The bulk document API allows you to create, update, and delete multiple documents at the same time within a single request. The basic operation is similar to creating, updating, or deleting a single document, except that you batch the document structure and information.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.data-document.write
cloudantnosqldb.design-document.write
cloudantnosqldb.local-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.data-document.write
cloudantnosqldb.design-document.write
cloudantnosqldb.local-document.write

Request

Request Body

Path Parameters

Query Parameters

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

507 -

Bulk query revision information for multiple documents

POST /{db}/_bulk_get

Fetch specific revisions or revision histories for multiple documents in bulk as replicators do.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

attachments

boolean

att_encoding_info

boolean

latest

boolean

Query parameter to specify whether to force retrieving latest leaf revision, no matter what rev was requested.

revs

boolean

Query parameter to specify whether to include a list of all known document revisions.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Note

Before using the changes feed read the FAQs to understand the limitations and appropriate use cases.

To use some filter types you must use the `POST` version of this request. ">

Query the database document changes feed (GET)

GET /{db}/_changes

Returns a sorted list of changes made to documents in the database, in time order of application. Only the most recent change for a specific document is included in the list. For example, if you add fields to a document and then delete them, an API client that checks for changes might not know about the intermediate state of added documents. These checks listen for updates to the database for post processing or synchronization, and for practical purposes, a continuously connected `_changes` feed is a reasonable approach for generating a real-time log for most applications.

Note

Before using the changes feed read the FAQs to understand the limitations and appropriate use cases.

To use some filter types you must use the `POST` version of this request.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

att_encoding_info

boolean

attachments

boolean

conflicts

boolean

descending

boolean

Query parameter to specify whether to return changes in the descending order with most recent change first. The `since` parameter has no effect when using descending order.

doc_ids

array

Query parameter to specify a JSON array list of document IDs to restrict the changes feed to. Used with the `_doc_ids` filter. Since length of URL is limited, it is better to use POST `/{db}/_changes` instead.

feed

string

Query parameter to specify the changes feed type.

filter

string

Query parameter to specify a filter to emit only specific events from the changes stream.

The built-in filter types are: * `_design` - Returns only changes to design documents. * `_doc_ids` - Returns changes for documents with an ID matching one specified in `doc_ids` request body parameter. (`POST` only) * `_selector` - Returns changes for documents that match the `selector` request body parameter. The selector syntax is the same as used for `_find`. (`POST` only) * `_view` - Returns changes for documents that match an existing map function in the view specified by the query parameter `view`.

Additionally, the value can be the name of a JS filter function from a design document. For example: `design_doc/filtername`.

Note: For better performance use the built-in `_selector`, `_design` or `_doc_ids` filters rather than JS based `_view` or design document filters. If you need to pass values to change the filtered content use the `_selector` filter type.

heartbeat

integer

Query parameter to specify the period in milliseconds after which an empty line is sent in the results. Off by default and only applicable for `continuous` and `eventsource` feeds. Overrides any timeout to keep the feed alive indefinitely. May also be `true` to use a value of `60000`.

Note: Delivery of heartbeats cannot be relied on at specific intervals. If your application runs in an environment where idle network connections may break, `heartbeat` is not suitable as a keepalive mechanism. Instead, consider one of the following options: * Use the `timeout` parameter with a value that is compatible with your network environment. * Switch to scheduled usage of one of the non-continuous changes feed types (`normal` or `longpoll`). * Use TCP keepalive.

include_docs

boolean

Query parameter to specify whether to include the full content of the documents in the response.

last_event_id

Query parameter to specify the ID of the last events received by the server on a previous connection. Alias of `Last-Event-ID` header.

limit

integer

Query parameter to specify the number of returned documents to limit the result to.

seq_interval

integer

Query parameter to specify that the update seq should only be calculated with every Nth result returned. When fetching changes in a batch, setting <code>seq_interval=<batch size></code>, where <batch size> is the number of results requested per batch, load can be reduced on the source database as computing the seq value across many shards (especially in highly-sharded databases) is expensive.

since

Query parameter to specify to start the results from the change immediately after the given update sequence. Possible values are: * `0` for all available changes (default). * `now` for future changes. * A valid update sequence, for example, from the `seq` value of a change received before.

style

string

Query parameter to specify how many revisions are returned in the changes array. The default, `main_only`, will only return the current "winning" revision; all_docs will return all leaf revisions (including conflicts and deleted former conflicts).

timeout

integer

Query parameter to specify the maximum period in milliseconds to wait for a change before the response is sent, even if there are no results. Only applicable for `longpoll` or `continuous` feeds. Default value is specified by `httpd/changes_timeout` configuration option. Note that `60000` value is also the default maximum timeout to prevent undetected dead connections.

view

string

Query parameter to specify a view function as a filter. Documents pass the filter if the view's map function emits at least one record for them.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Note

Before using the changes feed read the FAQs to understand the limitations and appropriate use cases.

If you need to pass parameters to dynamically change the filtered content use the `_selector` filter type for better performance and compatibility. The SDKs have full support for change requests using selector filters, but don't support passing parameters to design document filters. ">

Query the database document changes feed

POST /{db}/_changes

Requests the database changes feed in the same way as `GET /{db}/_changes` does. It is widely used with the `filter` query parameter because it allows one to pass more information to the filter.

Note

Before using the changes feed read the FAQs to understand the limitations and appropriate use cases.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

att_encoding_info

boolean

attachments

boolean

conflicts

boolean

descending

boolean

Query parameter to specify whether to return changes in the descending order with most recent change first. The `since` parameter has no effect when using descending order.

feed

string

Query parameter to specify the changes feed type.

filter

string

Query parameter to specify a filter to emit only specific events from the changes stream.

Additionally, the value can be the name of a JS filter function from a design document. For example: `design_doc/filtername`.

heartbeat

integer

include_docs

boolean

Query parameter to specify whether to include the full content of the documents in the response.

last_event_id

Query parameter to specify the ID of the last events received by the server on a previous connection. Alias of `Last-Event-ID` header.

limit

integer

Query parameter to specify the number of returned documents to limit the result to.

seq_interval

integer

since

style

string

timeout

integer

view

string

Query parameter to specify a view function as a filter. Documents pass the filter if the view's map function emits at least one record for them.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Delete a design document

DELETE /{db}/_design/{ddoc}

Marks the specified design document as deleted by adding a `_deleted` field with the value `true`. Documents with this field are not returned with requests but stay in the database. You must supply the current (latest) revision, either by using the `rev` parameter or by using the `If-Match` header to specify the revision.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.design-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.design-document.write

Request

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

rev

Query parameter to specify a document revision.

Response

200 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve a design document

GET /{db}/_design/{ddoc}

Returns design document with the specified `doc_id` from the specified database. Unless you request a specific revision, the current revision of the design document is always returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

attachments

boolean

att_encoding_info

boolean

atts_since

array

Query parameter to specify whether to include attachments only since specified revisions. Note this does not include the attachments for the specified revisions.

conflicts

boolean

deleted_conflicts

boolean

Query parameter to specify whether to include a list of deleted conflicted revisions in the `_deleted_conflicts` property of the returned document.

latest

boolean

Query parameter to specify whether to force retrieving latest leaf revision, no matter what rev was requested.

local_seq

boolean

Query parameter to specify whether to include the last update sequence for the document.

open_revs

array

Query parameter to specify leaf revisions to retrieve. Additionally, it accepts a value of `all` to return all leaf revisions.

rev

Query parameter to specify a document revision.

revs

boolean

Query parameter to specify whether to include a list of all known document revisions.

revs_info

boolean

Query parameter to specify whether to includes detailed information for all known document revisions.

Response

200 -

304 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve the HTTP headers for a design document

HEAD /{db}/_design/{ddoc}

This method supports the same query arguments as the `GET /{db}/_design/{ddoc}` method, but the results include only the header information (including design document size, and the revision as an ETag). The ETag header shows the current revision for the requested design document, and if you requested the design document in full, the Content-Length specifies the length of the data. If you add any of the query arguments, then the resulting HTTP headers correspond to what is returned for the equivalent GET request.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

Response

200 -

304 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Create or modify a design document

PUT /{db}/_design/{ddoc}

The PUT method creates a new named design document, or creates a new revision of the existing design document.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.design-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.design-document.write

Request

Request Body

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

new_edits

boolean

Avoid using this parameter, since this option applies document revisions without checking for conflicts, so it is very easy to accidentally end up with a large number of conflicts.

rev

Query parameter to specify a document revision.

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

507 -

Copy a design document

X-COPY /{db}/_design/{ddoc}

The COPY operation, which is non-standard HTTP, copies an existing design document to a new or existing design document. The source design document is specified on the request line, with the Destination header of the request specifying the target design document. Given that view indexes on disk are named after their MD5 hash of the view definition, and that a COPY operation won't change that definition, the copied views won't have to be reconstructed. Both views are served from the same index on disk.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

In addition to `cloudantnosqldb.any-document.read` this operation requires one of the three `write` permissions appropriate to the destination document type.

cloudantnosqldb.any-document.read
cloudantnosqldb.data-document.write
cloudantnosqldb.design-document.write
cloudantnosqldb.local-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read
cloudantnosqldb.data-document.write
cloudantnosqldb.design-document.write
cloudantnosqldb.local-document.write

Request

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

rev

Query parameter to specify a document revision.

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

429 -

500 -

502 -

503 -

504 -

507 -

Retrieve information about a design document

GET /{db}/_design/{ddoc}/_info

Retrieves information about the specified design document, including the index, index size, and current status of the design document and associated index information.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Query a search index (GET)

GET /{db}/_design/{ddoc}/_search/{index}

Search indexes, which are defined in design documents, allow databases to be queried by using Lucene Query Parser Syntax. An index function defines search indexes, similar to a map function in MapReduce views. The index function decides what data to index and what data to store in the index.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

query

Required *

string

Query parameter to specify a Lucene search query. Alias of `q`.

bookmark

Query parameter to specify a bookmark that was received from a previous request. This parameter enables paging through the results. If there are no more results after the bookmark, you get a response containing no further results and the same bookmark, confirming the end of the result list.

counts

array

Query parameter to specify an array of names of string fields, for which counts are requested. The response contains counts for each unique value of the string field name among the documents that match the search query. Faceting must be enabled for this parameter to function.

drilldown

array

Restrict results to documents with a dimension equal to the specified label(s). The search matches only documents containing the value that was provided in the named field. It differs from using "fieldname:value" in the q parameter only in that the values are not analyzed. Faceting must be enabled for this parameter to function.

group_field

string

Query parameter to specify the field name by which to group search matches. It must be a string that contains the name of a string field. Fields containing other data such as numbers, objects, or arrays cannot be used.

group_limit

integer

Query parameter to specify the maximum group count. This parameter can be used only if group_field is specified.

group_sort

array

Query parameter to specify the order of the groups in a search that uses group_field. The default sort order is relevance. This parameter can have the same values as the sort field, so single fields and arrays of fields are supported.

highlight_fields

array

Query parameter to specify which fields to highlight. If specified, the result object contains a highlights field with an entry for each specified field.

highlight_pre_tag

string

Query parameter to specify a string that is inserted before the highlighted word in the highlights output.

highlight_post_tag

string

Query parameter to specify a string that is inserted after the highlighted word in the highlights output.

highlight_number

integer

Query parameter to specify the number of fragments that are returned in highlights. If the search term occurs less often than the number of fragments that are specified, longer fragments are returned.

highlight_size

integer

Query parameter to specify the number of characters in each fragment for highlights.

include_docs

boolean

Query parameter to specify whether to include the full content of the documents in the response.

include_fields

array

Query parameter to specify a JSON array of field names to include in search results. Any fields that are included must be indexed with the `store:true` option. The default is all fields.

limit

integer

Query parameter to specify the number of returned documents to limit the result to.

ranges

string

Query parameter to specify ranges for faceted, numeric search fields. The value is a JSON object where the fields names are faceted numeric search fields, and the values of the fields are JSON objects. For each of these objects the field names of the JSON objects are names for ranges. The values are strings that describe the range, for example "[0 TO 10]".

sort

array

Query parameter to specify the sort order of the results. In a grouped search (when group_field is used), this parameter specifies the sort order within a group. The default sort order is relevance. A JSON string of the form "fieldname<type>" or -fieldname<type> for descending order, where fieldname is the name of a string or number field, and type is either a number, a string, or a JSON array of strings. The type part is optional, and defaults to number. Some examples are "foo", "-foo", "bar<string>", "-foo<number>" and ["-foo<number>", "bar<string>"]. String fields that are used for sorting must not be analyzed fields. Fields that are used for sorting must be indexed by the same indexer that is used for the search query.

stale

string

Query parameter to specify to not wait for the index to finish building before returning results.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Query a search index

POST /{db}/_design/{ddoc}/_search/{index}

Search indexes, which are defined in design documents, allow databases to be queried by using Lucene Query Parser Syntax. An index function defines a search index, similar to a map function in MapReduce views. The index function decides what data to index and what data to store in the index. The advantage of using the HTTP `POST` method is that the query is submitted as a JSON object in the request body. This avoids the limitations of passing query options as URL query parameters of a `GET` request.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Retrieve information about the search index disk size

GET /{db}/_design/{ddoc}/_search_disk_size/{index}

Retrieve size of the search index on disk.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve information about a search index

GET /{db}/_design/{ddoc}/_search_info/{index}

Retrieve search index metadata information, such as the size of the index on disk.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Query a MapReduce view (GET)

GET /{db}/_design/{ddoc}/_view/{view}

This operation queries the specified MapReduce view of the specified design document. By default, the map and reduce functions of the view are run to update the view before returning the response.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

att_encoding_info

boolean

attachments

boolean

conflicts

boolean

descending

boolean

Query parameter to specify whether to return rows in descending by key order.

end_key

string

Query parameter to specify to stop returning records when the specified key is reached. String representation of any JSON type that matches the key type emitted by the view function.

end_key_doc_id

string

Query parameter to stop returning rows at the specified document ID. No effect if using `group` or not providing end key.

group

boolean

Query parameter to specify whether to group reduced results by key. Valid only if a reduce function is defined in the view. If the view emits keys in JSON array format, then it is possible to reduce groups further based on the number of array elements with the `group_level` parameter.

group_level

integer

Query parameter to specify a group level to be used. Only applicable if the view uses keys that are JSON arrays. Implies group is `true`. Group level groups the reduced results by the specified number of array elements. If unset, results are grouped by the entire array key, returning a reduced value for each complete key.

include_docs

boolean

Query parameter to specify whether to include the full content of the documents in the response.

inclusive_end

boolean

Query parameter to specify whether the specified end key should be included in the result.

key

string

Query parameter to specify to return only rows that match the specified key. String representation of any JSON type that matches the key type emitted by the view function.

keys

string

limit

integer

Query parameter to specify the number of returned documents to limit the result to.

reduce

boolean

Query parameter to specify whether to use the reduce function in a map-reduce view. Default is true when a reduce function is defined. A default `reduce` view type can be disabled to behave like a `map` by setting `reduce=false` explicitly. Be aware that `include_docs=true` is only for `map` views. Reduced views do not include document IDs in view rows.

skip

integer

Query parameter to specify the number of records before starting to return the results.

sorted

boolean

Query parameter to specify whether to sort the returned rows. Setting this to false offers a performance boost. The total_rows and offset fields are not available when this is set to false.

stable

boolean

Query parameter to specify whether use the same replica of the index on each request. The default value `false` contacts all replicas and returns the result from the first, fastest, responder. Setting it to `true` when used in conjunction with `update=false` may improve consistency at the expense of increased latency and decreased throughput, if the selected replica is not the fastest of the available replicas.

Note: In general setting `true` is discouraged and is strictly not recommended when using `update=true`.

stale

string

Note: `stale` is deprecated, use `stable` and `update` instead.

Query parameter to specify whether to allow the results from a stale view to be used, without triggering a rebuild of all views within the encompassing design doc.

`ok` is equivalent to `stable=true&update=false`
`update_after` is equivalent to `stable=true&update=lazy`

For more details on the use cases of `stale`, `update`, and `stable` parameters, see this blog post.

start_key

string

Query parameter to specify to start returning records from the specified key. String representation of any JSON type that matches the key type emitted by the view function.

start_key_doc_id

string

Query parameter to start returning rows at the specified document ID. No effect if using `group` or not providing start key.

update

string

Query parameter to specify whether or not the view in question should be updated prior to responding to the user.

`true` - Return results after the view is updated.
`false` - Return results without updating the view.
`lazy` - Return the view results without waiting for an update, but update them immediately after the request.

update_seq

boolean

Query parameter to specify whether to include in the response an update_seq value indicating the sequence id of the database the view reflects.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

507 -

Query a MapReduce view

POST /{db}/_design/{ddoc}/_view/{view}

This operation queries the specified MapReduce view of the specified design document. By default, the map and reduce functions of the view are run to update the view before returning the response. The advantage of using the HTTP `POST` method is that the query is submitted as a JSON object in the request body. This avoids the limitations of passing query options as URL query parameters of a `GET` request.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

507 -

Multi-query a MapReduce view

POST /{db}/_design/{ddoc}/_view/{view}/queries

This operation runs multiple specified view queries against the view function from the specified design document.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

507 -

Query a list of all design documents in a database (GET)

GET /{db}/_design_docs

Queries the index of all design document IDs. The results matching the query parameters are returned in a JSON object, including a list of matching design documents with basic contents, such as the ID and revision. When no query parameters are specified, results for all design documents in the database are returned. Optionally, the design document content or additional metadata can be included in the response.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

conflicts

boolean

descending

boolean

Query parameter to specify whether to return rows in descending by key order.

end_key

string

Query parameter to specify to stop returning records when the specified key is reached. String representation of any JSON type that matches the key type emitted by the view function.

end_key_doc_id

string

Query parameter to stop returning rows at the specified document ID. No effect if using `group` or not providing end key.

include_docs

boolean

Query parameter to specify whether to include the full content of the documents in the response.

inclusive_end

boolean

Query parameter to specify whether the specified end key should be included in the result.

key

string

Query parameter to specify to return only rows that match the specified key. String representation of any JSON type that matches the key type emitted by the view function.

keys

string

limit

integer

Query parameter to specify the number of returned documents to limit the result to.

skip

integer

Query parameter to specify the number of records before starting to return the results.

start_key

string

Query parameter to specify to start returning records from the specified key. String representation of any JSON type that matches the key type emitted by the view function.

start_key_doc_id

string

Query parameter to start returning rows at the specified document ID. No effect if using `group` or not providing start key.

update_seq

boolean

Query parameter to specify whether to include in the response an update_seq value indicating the sequence id of the database the view reflects.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Query a list of all design documents in a database

POST /{db}/_design_docs

Queries the index of all design document IDs. The results matching the request body parameters are returned in a JSON object, including a list of matching design documents with basic contents, such as the ID and revision. When no request body parameters are specified, results for all design documents in the database are returned. Optionally, the design document content or additional metadata can be included in the response.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Multi-query the list of all design documents

POST /{db}/_design_docs/queries

This operation runs multiple view queries of all design documents in the database. This operation enables you to request numerous queries in a single request, in place of multiple POST `/{db}/_design_docs` requests.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Retrieve information about which index is used for a query

POST /{db}/_explain

Shows which index is being used by the query. Parameters are the same as the `_find` endpoint.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Query an index by using selector syntax

POST /{db}/_find

Query documents by using a declarative JSON querying syntax. It's best practice to create an appropriate index for all fields in selector by using the `_index` endpoint.

Queries without an appropriate backing index by default fallback to using the built-in `_all_docs` index. This isn't recommended because it has a significant performance impact causing a full scan of the database with each request. In this case the response body includes a warning field recommending the creation of an index.

To avoid the fallback behavior set the `allow_fallback` option to `false` and the server responds with a `400` status code if no suitable index exists. If you want to use only a specific index for your query set `allow_fallback` to `false` and set the `use_index` option.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

507 -

Retrieve information about all indexes

GET /{db}/_index

When you make a GET request to `/db/_index`, you get a list of all the indexes using `"language":"query"` in the database and the primary index. In addition to the information available through this API, the indexes are stored in the `indexes` property of their respective design documents.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Create a new index on a database

POST /{db}/_index

Create a new index on a database.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.design-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.design-document.write

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Delete an index

DELETE /{db}/_index/_design/{ddoc}/{type}/{index}

Delete the index functions from the design document and index files on the server.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.design-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.design-document.write

Request

Path Parameters

db

Required *

Path parameter to specify the database name.

ddoc

Required *

Path parameter to specify the design document name. The design document name is the design document ID excluding the `_design/` prefix.

type

Required *

Path parameter to specify the index type.

index

Required *

string

Path parameter to specify the index name.

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Delete a local document

DELETE /{db}/_local/{doc_id}

Deletes the specified local document. The semantics are identical to deleting a standard document in the specified database, except that the document is not replicated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.local-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.local-document.write

Request

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

Response

200 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve a local document

GET /{db}/_local/{doc_id}

Retrieves the specified local document. The semantics are identical to accessing a standard document in the specified database, except that the document is not replicated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

attachments

boolean

att_encoding_info

boolean

atts_since

array

Query parameter to specify whether to include attachments only since specified revisions. Note this does not include the attachments for the specified revisions.

local_seq

boolean

Query parameter to specify whether to include the last update sequence for the document.

Response

200 -

304 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve HTTP headers for a local document

HEAD /{db}/_local/{doc_id}

Retrieves the HTTP headers containing minimal amount of information about the specified local document. Since the response body is empty, using the HEAD method is a lightweight way to check if the local document exists or not.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

Response

200 -

304 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Create or modify a local document

PUT /{db}/_local/{doc_id}

Stores the specified local document. The semantics are identical to storing a standard document in the specified database, except that the document is not replicated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.local-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.local-document.write

Request

Request Body

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

507 -

Copy a local document

X-COPY /{db}/_local/{doc_id}

Copies the specified local document. The semantics are identical to copying a standard document in the specified database, except that the document is not replicated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

In addition to `cloudantnosqldb.any-document.read` this operation requires one of the three `write` permissions appropriate to the destination document type.

cloudantnosqldb.any-document.read
cloudantnosqldb.data-document.write
cloudantnosqldb.design-document.write
cloudantnosqldb.local-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read
cloudantnosqldb.data-document.write
cloudantnosqldb.design-document.write
cloudantnosqldb.local-document.write

Request

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

507 -

Retrieve information about a database partition

GET /{db}/_partition/{partition_key}

Given a partition key, return the database name, sizes, partition, doc count, and doc delete count.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve HTTP headers for information about a database partition

HEAD /{db}/_partition/{partition_key}

Retrieves the HTTP headers for information about a database partition.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Query a list of all documents in a database partition (GET)

GET /{db}/_partition/{partition_key}/_all_docs

Queries the primary index (all document IDs). The results that match the query parameters are returned in a JSON object, including a list of matching documents with basic contents, such as the ID and revision. When no query parameters are specified, results for all documents in the database partition are returned. Optionally, document content or additional metadata can be included in the response.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

conflicts

boolean

descending

boolean

Query parameter to specify whether to return rows in descending by key order.

end_key

string

Query parameter to specify to stop returning records when the specified key is reached. String representation of any JSON type that matches the key type emitted by the view function.

end_key_doc_id

string

Query parameter to stop returning rows at the specified document ID. No effect if using `group` or not providing end key.

include_docs

boolean

Query parameter to specify whether to include the full content of the documents in the response.

inclusive_end

boolean

Query parameter to specify whether the specified end key should be included in the result.

key

string

Query parameter to specify to return only rows that match the specified key. String representation of any JSON type that matches the key type emitted by the view function.

keys

string

limit

integer

Query parameter to specify the number of returned documents to limit the result to.

skip

integer

Query parameter to specify the number of records before starting to return the results.

start_key

string

Query parameter to specify to start returning records from the specified key. String representation of any JSON type that matches the key type emitted by the view function.

start_key_doc_id

string

Query parameter to start returning rows at the specified document ID. No effect if using `group` or not providing start key.

update_seq

boolean

Query parameter to specify whether to include in the response an update_seq value indicating the sequence id of the database the view reflects.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Query a list of all documents in a database partition

POST /{db}/_partition/{partition_key}/_all_docs

Queries the primary index (all document IDs). The results that match the query parameters are returned in a JSON object, including a list of matching documents with basic contents, such as the ID and revision. When no query parameters are specified, results for all documents in the database partition are returned. Optionally, document content or additional metadata can be included in the response.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Query a database partition search index (GET)

GET /{db}/_partition/{partition_key}/_design/{ddoc}/_search/{index}

Partitioned Search indexes, which are defined in design documents, allow partition databases to be queried by using Lucene Query Parser Syntax. Search indexes are defined by an index function, similar to a map function in MapReduce views. The index function decides what data to index and store in the index.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

query

Required *

string

Query parameter to specify a Lucene search query. Alias of `q`.

bookmark

highlight_fields

array

Query parameter to specify which fields to highlight. If specified, the result object contains a highlights field with an entry for each specified field.

highlight_pre_tag

string

Query parameter to specify a string that is inserted before the highlighted word in the highlights output.

highlight_post_tag

string

Query parameter to specify a string that is inserted after the highlighted word in the highlights output.

highlight_number

integer

highlight_size

integer

Query parameter to specify the number of characters in each fragment for highlights.

include_docs

boolean

Query parameter to specify whether to include the full content of the documents in the response.

include_fields

array

Query parameter to specify a JSON array of field names to include in search results. Any fields that are included must be indexed with the `store:true` option. The default is all fields.

limit

integer

Query parameter to specify the number of returned documents to limit the result to.

sort

array

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

FAQs to understand the limitations and appropriate use cases. ">

Query a database partition search index

POST /{db}/_partition/{partition_key}/_design/{ddoc}/_search/{index}

Before using read the FAQs to understand the limitations and appropriate use cases.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Query a database partition MapReduce view function (GET)

GET /{db}/_partition/{partition_key}/_design/{ddoc}/_view/{view}

This operation queries the specified MapReduce view of the specified design document. By default, the map and reduce functions of the view are run to update the view before returning the response.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

conflicts

boolean

descending

boolean

Query parameter to specify whether to return rows in descending by key order.

end_key

string

Query parameter to specify to stop returning records when the specified key is reached. String representation of any JSON type that matches the key type emitted by the view function.

end_key_doc_id

string

Query parameter to stop returning rows at the specified document ID. No effect if using `group` or not providing end key.

group

boolean

group_level

integer

include_docs

boolean

Query parameter to specify whether to include the full content of the documents in the response.

inclusive_end

boolean

Query parameter to specify whether the specified end key should be included in the result.

key

string

Query parameter to specify to return only rows that match the specified key. String representation of any JSON type that matches the key type emitted by the view function.

keys

string

limit

integer

Query parameter to specify the number of returned documents to limit the result to.

reduce

boolean

skip

integer

Query parameter to specify the number of records before starting to return the results.

sorted

boolean

Query parameter to specify whether to sort the returned rows. Setting this to false offers a performance boost. The total_rows and offset fields are not available when this is set to false.

start_key

string

Query parameter to specify to start returning records from the specified key. String representation of any JSON type that matches the key type emitted by the view function.

start_key_doc_id

string

Query parameter to start returning rows at the specified document ID. No effect if using `group` or not providing start key.

update

string

Query parameter to specify whether or not the view in question should be updated prior to responding to the user.

`true` - Return results after the view is updated.
`false` - Return results without updating the view.
`lazy` - Return the view results without waiting for an update, but update them immediately after the request.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

507 -

FAQs to understand the limitations and appropriate use cases. ">

Query a database partition MapReduce view function

POST /{db}/_partition/{partition_key}/_design/{ddoc}/_view/{view}

Runs the specified view function from the specified design document. Unlike `GET /{db}/_design/{ddoc}/_view/{view}` for accessing views, the POST method supports the specification of explicit keys to be retrieved from the view results. The remainder of the POST view functionality is identical to the `GET /{db}/_design/{ddoc}/_view/{view}` API.

Before using read the FAQs to understand the limitations and appropriate use cases.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

507 -

Retrieve information about which partition index is used for a query

POST /{db}/_partition/{partition_key}/_explain

Shows which index is being used by the query. Parameters are the same as the `/{db}/_partition/{partition_key}/_find` endpoint.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

FAQs to understand the limitations and appropriate use cases.">

Query a database partition index by using selector syntax

POST /{db}/_partition/{partition_key}/_find

Query documents by using a declarative JSON querying syntax. It's best practice to create an appropriate index for all fields in selector by using the `_index` endpoint.

Queries without an appropriate backing index by default fallback to using the built-in `_all_docs` index. This isn't recommended because it has a significant performance impact causing a full scan of the partition with each request. In this case the response body includes a warning field recommending the creation of an index.

Before using read the FAQs to understand the limitations and appropriate use cases.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

507 -

Query the document revisions and possible ancestors missing from the database

POST /{db}/_revs_diff

The replicator is the primary user of this operation. After receiving a set of new revision IDs from the source database, the replicator sends this set to the destination database's `_revs_diff` to find out which of them already exists there. It can then avoid fetching and sending already-known document bodies.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Request Body

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Retrieve shard information

GET /{db}/_shards

List each shard range and the corresponding replicas for a specified database.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.database-shards.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.database-shards.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve shard information for a specific document

GET /{db}/_shards/{doc_id}

Retrieves information about a specific shard where a particular document is stored, along with information about the nodes where that shard has a replica.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.database-shards.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.database-shards.read

Request

Path Parameters

Query Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Delete a document

DELETE /{db}/{doc_id}

Marks the specified document as deleted by adding a `_deleted` field with the value `true`. Documents with this field are not returned within requests anymore but stay in the database. You must supply the current (latest) revision, either by using the `rev` parameter or by using the `If-Match` header to specify the revision.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.data-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.data-document.write

Request

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

rev

Query parameter to specify a document revision.

Response

200 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve a document

GET /{db}/{doc_id}

Returns document with the specified `doc_id` from the specified database. Unless you request a specific revision, the latest revision of the document is always returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

attachments

boolean

att_encoding_info

boolean

atts_since

array

Query parameter to specify whether to include attachments only since specified revisions. Note this does not include the attachments for the specified revisions.

conflicts

boolean

deleted_conflicts

boolean

Query parameter to specify whether to include a list of deleted conflicted revisions in the `_deleted_conflicts` property of the returned document.

latest

boolean

Query parameter to specify whether to force retrieving latest leaf revision, no matter what rev was requested.

local_seq

boolean

Query parameter to specify whether to include the last update sequence for the document.

open_revs

array

Query parameter to specify leaf revisions to retrieve. Additionally, it accepts a value of `all` to return all leaf revisions.

rev

Query parameter to specify a document revision.

revs

boolean

Query parameter to specify whether to include a list of all known document revisions.

revs_info

boolean

Query parameter to specify whether to includes detailed information for all known document revisions.

Response

200 -

304 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve the HTTP headers for the document

HEAD /{db}/{doc_id}

This method supports the same query arguments as the `GET /{db}/{docid}` method, but only the header information (including document size and the revision as an ETag) is returned. The ETag header shows the current revision for the requested document, and the Content-Length specifies the length of the data if the document was requested in full. Add any of the query arguments, then the resulting HTTP headers that correspond to it are returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

latest

boolean

Query parameter to specify whether to force retrieving latest leaf revision, no matter what rev was requested.

rev

Query parameter to specify a document revision.

Response

200 -

304 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

Create or modify a document

PUT /{db}/{doc_id}

Creates or modifies a document in the specified database.

For creation, you must specify the document ID but you should not specify the revision.

For modification, you must specify the document ID and a revision identifier.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.data-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.data-document.write

Request

Request Body

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

new_edits

boolean

Avoid using this parameter, since this option applies document revisions without checking for conflicts, so it is very easy to accidentally end up with a large number of conflicts.

rev

Query parameter to specify a document revision.

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

507 -

Copy a document

X-COPY /{db}/{doc_id}

The COPY (which is non-standard HTTP) method copies an existing document to a new or existing document. The source document is specified on the request line, with the Destination header of the request specifying the target document.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

In addition to `cloudantnosqldb.any-document.read` this operation requires one of the three `write` permissions appropriate to the destination document type.

cloudantnosqldb.any-document.read
cloudantnosqldb.data-document.write
cloudantnosqldb.design-document.write
cloudantnosqldb.local-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read
cloudantnosqldb.data-document.write
cloudantnosqldb.design-document.write
cloudantnosqldb.local-document.write

Request

Path Parameters

Query Parameters

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

rev

Query parameter to specify a document revision.

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

429 -

500 -

502 -

503 -

504 -

507 -

Delete an attachment

DELETE /{db}/{doc_id}/{attachment_name}

Deletes the attachment with the filename, `{attachment_name}`, from the specified doc. You must supply the `rev` query parameter or `If-Match` header with the current revision to delete the attachment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.data-document.write

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.data-document.write

Request

Path Parameters

Query Parameters

rev

Query parameter to specify a document revision.

batch

string

Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

429 -

500 -

502 -

503 -

504 -

Retrieve an attachment

GET /{db}/{doc_id}/{attachment_name}

Returns the file attachment that is associated with the document. The raw data of the associated attachment is returned, just as if you were accessing a static file. The returned Content-Type header is the same as the content type set when the document attachment was submitted to the database.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

rev

Query parameter to specify a document revision.

Response

200 -

206 -

304 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

416 -

429 -

500 -

502 -

503 -

504 -

Retrieve the HTTP headers for an attachment

HEAD /{db}/{doc_id}/{attachment_name}

Returns the HTTP headers that contain a minimal amount of information about the specified attachment. This method supports the same query arguments as the `GET /{db}/{doc_id}/{attachment_name}` method, but only the header information (including attachment size, encoding, and the MD5 hash as an ETag), is returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

cloudantnosqldb.any-document.read

Auditing

Calling this method generates the following auditing event.

cloudantnosqldb.any-document.read

Request

Path Parameters

Query Parameters

rev

Query parameter to specify a document revision.

Response

200 -

206 -

304 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

416 -

429 -

500 -

502 -

503 -

504 -

Create or modify an attachment

PUT /{db}/{doc_id}/{attachment_name}

Uploads the supplied content as an attachment to the specified document. The attachment name that you provide must be a URL encoded string. You must supply the Content-Type header, and for an existing document, you must also supply either the `rev` query argument or the `If-Match` HTTP header. If you omit the revision, a new, otherwise empty, document is created with the provided attachment, or a conflict occurs. If the uploaded attachment uses an existing attachment name in the remote database, it updates the corresponding stored content of the database. Since you must supply the revision information to add an attachment to the document, this serves as validation to update the existing attachment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.