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

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

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

Parameters

descending

boolean

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

Default: false

endKey

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.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

limit

number

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

skip

number

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

Default: 0

startKey

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.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

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

Parameters

keys

Required *

string[]

A list of database names.

Example: ["products","users","orders"]

Constraints:

• Max items: 100

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

Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

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

Parameters

docId

Required *

string

Path parameter to specify the ID of the stored replication configuration in the `_replicator` database.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

ifMatch

string

Header parameter for a conditional HTTP request matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

batch

string

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

Allowed values: ok

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

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

Parameters

docId

Required *

string

Path parameter to specify the ID of the stored replication configuration in the `_replicator` database.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

ifNoneMatch

string

Header parameter for a conditional HTTP request not matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

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.

Default: false

attEncodingInfo

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.

Default: false

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.

Default: false

deletedConflicts

boolean

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

Default: false

latest

boolean

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

Default: false

localSeq

boolean

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

Default: false

meta

boolean

Query parameter to specify whether to include document meta information. Acts the same as specifying all of the conflicts, deleted_conflicts and open_revs query parameters.

Default: false

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

revs

boolean

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

Default: false

revsInfo

boolean

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

Default: false

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

Parameters

docId

Required *

string

Path parameter to specify the ID of the stored replication configuration in the `_replicator` database.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

ifNoneMatch

string

Header parameter for a conditional HTTP request not matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

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

Parameters

docId

Required *

string

Path parameter to specify the ID of the stored replication configuration in the `_replicator` database.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

replicationDocument

Required *

ReplicationDocument

HTTP request body for replication operations.

Example: {"cancel":false,"checkpoint_interval":4500,"connection_timeout":15000,"continuous":true,"create_target":true,"create_target_params":{"q":1},"doc_ids":["badger","lemur","llama"],"filter":"ddoc/my_filter","http_connections":10,"request_compression":"gzip","retries_per_request":3,"selector":{"_id":{"$regex":"docid"}},"since_seq":"34-g1AAAAGjeJzLYWBgYMlgTmGQT0lKzi9KdU","socket_options":"[{keepalive, true}, {nodelay, false}]","source":{"url":"https://my-source-instance.cloudantnosqldb.appdomain.cloud.example/animaldb"},"target":{"auth":{"iam":{"api_key":"iam_api_key"}},"url":"https://my-target-instance.cloudantnosqldb.appdomain.cloud.example/animaldb-target"},"use_checkpoints":false,"user_ctx":{"name":"john","roles":["_replicator"]},"worker_batch_size":400,"worker_processes":3}

ifMatch

string

Header parameter for a conditional HTTP request matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

batch

string

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

Allowed values: ok

newEdits

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.

Default: false

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

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

Parameters

limit

number

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

skip

number

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

Default: 0

states

string[]

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

Allowed values: initializing, error, pending, running, crashing, completed, failed

Constraints:

• Min items: 1
• Max items: 7

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

Parameters

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

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

Parameters

limit

number

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

Default: 25

skip

number

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

Default: 0

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

Parameters

jobId

Required *

string

Path parameter to specify the replication job id.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].*$/

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

Parameters

jobId

Required *

string

Path parameter to specify the replication job id.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].*$/

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

Parameters

analyzer

Required *

string

The analyzer type that is being used at the tokenization.

Example: english

Allowed values: arabic, armenian, basque, brazilian, bulgarian, catalan, chinese, cjk, classic, czech, danish, dutch, email, english, finnish, french, galician, german, greek, hindi, hungarian, indonesian, irish, italian, japanese, keyword, latvian, norwegian, persian, polish, portuguese, romanian, russian, simple, spanish, standard, swedish, thai, turkish, whitespace

text

Required *

string

The text to tokenize with the analyzer.

Example: running is fun

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

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

Parameters

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

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

Parameters

count

number

Query parameter to specify the number of UUIDs to return.

Default: 1

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

document

Required *

Document | NodeJS.ReadableStream | Buffer

HTTP request body for Document operations.

Example: {"_id":"exampleid","brand":"Foo","colours":["red","green","black","blue"],"description":"Slim Colourful Design Electronic Cooking Appliance for ...","image":"assets/img/0gmsnghhew.jpg","keywords":["Foo","Scales","Weight","Digital","Kitchen"],"name":"Digital Kitchen Scales","price":14.99,"productId":"1000042","taxonomy":["Home","Kitchen","Small Appliances"],"type":"product"}

contentType

string

The type of the input.

Allowed values: application/json, multipart/mixed, multipart/related, application/octet-stream

Default: application/json

batch

string

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

Allowed values: ok

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

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.

Default: false

q

number

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.

Default: 16

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

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

attEncodingInfo

boolean

Parameter to specify whether to include the encoding information for compressed attachments. This only applies when requesting documents in the response.

Default: false

attachments

boolean

Parameter to specify whether to include attachment content in included document content or only the attachment metadata. This only applies when requesting documents in the response.

Default: false

conflicts

boolean

Parameter to specify whether to include a list of conflicted revisions in each returned document. This only applies when requesting documents in the response.

Default: false

descending

boolean

Parameter to specify whether to return the documents in descending by key order.

Default: false

includeDocs

boolean

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

Default: false

inclusiveEnd

boolean

Parameter to specify whether to include the specified end key in the result.

Default: true

limit

number

Parameter to specify the number of returned documents to limit the result to.

Example: 10

skip

number

Parameter to specify the number of records before starting to return the results.

Default: 0

updateSeq

boolean

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

Default: false

endKey

string

Schema for a document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

key

string

Schema for a document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

keys

string[]

Schema for a list of document IDs.

Constraints:

• Max items: 65535

startKey

string

Schema for a document ID.

Example: 0007741142412418284

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

queries

Required *

AllDocsQuery[]

An array of query objects with fields for the parameters of each individual view query to be executed. The field names and their meaning are the same as the query parameters of a regular `/_all_docs` request.

Example: [{"keys":["small-appliances:1000042","small-appliances:1000043"]},{"limit":3,"skip":2}]

Constraints:

• Min items: 1
• Max items: 65535

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

bulkDocs

Required *

BulkDocs | NodeJS.ReadableStream | Buffer

HTTP request body for postBulkDocs.

Example: {"docs":[{"_id":"0007241142412418284","date":"2019-01-28T10:44:22.000Z","eventType":"addedToBasket","productId":"1000042","type":"event","userid":"abc123"},{"_id":"0008001142412418285","date":"2019-01-28T12:30:00.000Z","eventType":"addedToBasket","productId":"1000043","type":"event","userid":"def456"}]}

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docs

Required *

BulkGetQueryDocument[]

List of document items to get in bulk.

Example: [{"id":"order00067","rev":"3-917fa2381192822767f010b95b45325b"},{"id":"order00067","rev":"4-a5be949eeb7296747cc271766e9a498b"}]

Constraints:

• Max items: 65535

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.

Default: false

attEncodingInfo

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.

Default: false

latest

boolean

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

Default: false

revs

boolean

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

Default: false

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

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.

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.

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docIds

string[]

Schema for a list of document IDs.

Example: ["0007741142412418284"]

Constraints:

• Max items: 65535

fields

string[]

JSON array that uses the field syntax. Use this parameter to specify which fields of a document must be returned. If it is omitted or empty, the entire document is returned.

Constraints:

• Max items: 65535

selector

JsonObject

JSON object describing criteria used to select documents. The selector specifies fields in the document, and provides an expression to evaluate with the field content or other data.

The selector object must: * Be structured as valid JSON. * Contain a valid query expression.

Using a selector is significantly more efficient than using a JavaScript filter function, and is the recommended option if filtering on document attributes only.

Elementary selector syntax requires you to specify one or more fields, and the corresponding values required for those fields. You can create more complex selector expressions by combining operators.

Operators are identified by the use of a dollar sign `$` prefix in the name field.

There are two core types of operators in the selector syntax:

• Combination operators: applied at the topmost level of selection. They are used to combine selectors. A combination operator takes a single argument. The argument is either another selector, or an array of selectors.
• Condition operators: are specific to a field, and are used to evaluate the value stored in that field. For instance, the basic `$eq` operator matches when the specified field contains a value that is equal to the supplied argument.

It is important for query performance to use appropriate selectors:

• Only equality operators such as `$eq`, `$gt`, `$gte`, `$lt`, and `$lte` (but not `$ne`) can be used as the basis of a query. You should include at least one of these in a selector.
• Some operators such as `$not`, `$or`, `$in`, and `$regex` cannot be answered from an index. For query selectors use these operators in conjunction with equality operators or create and use a partial index to reduce the number of documents that will need to be scanned.

See the Cloudant Docs for a list of all available combination and conditional operators.

For further reference see selector syntax.

lastEventId

string

Header parameter to specify the ID of the last events received by the server on a previous connection. Overrides `since` query parameter.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^0|([1-9]\\d*-[A-Za-z0-9-_]+)|now$/

attEncodingInfo

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.

Default: false

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.

Default: false

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.

Default: false

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.

Default: false

feed

string

Query parameter to specify the changes feed type.

Allowed values: continuous, eventsource, longpoll, normal

Default: normal

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.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^_design|_docs_ids|_selector|_view|.*\/.*$/

heartbeat

number

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.

includeDocs

boolean

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

Default: false

limit

number

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

seqInterval

number

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=&lt;batch size&gt;</code>, where &lt;batch size&gt; 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

string

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.

Example: 0

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^0|([1-9]\\d*-[A-Za-z0-9-_]+)|now$/

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).

Allowed values: main_only, all_docs

Default: main_only

timeout

number

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.

Default: 60000

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.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].*$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

ifMatch

string

Header parameter for a conditional HTTP request matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

batch

string

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

Allowed values: ok

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

ifNoneMatch

string

Header parameter for a conditional HTTP request not matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

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.

Default: false

attEncodingInfo

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.

Default: false

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.

Default: false

deletedConflicts

boolean

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

Default: false

latest

boolean

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

Default: false

localSeq

boolean

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

Default: false

meta

boolean

Query parameter to specify whether to include document meta information. Acts the same as specifying all of the conflicts, deleted_conflicts and open_revs query parameters.

Default: false

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

revs

boolean

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

Default: false

revsInfo

boolean

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

Default: false

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

ifNoneMatch

string

Header parameter for a conditional HTTP request not matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

designDocument

Required *

DesignDocument

HTTP request body for DesignDocument operations.

Example: {"_id":"_design/appliances","_rev":"8-7e2537e5989294471061e0cfd7292725","indexes":{"findByPrice":{"analyzer":{"name":"standard"},"index":"function (doc) {\n index(\"price\", doc.price);\n}"}},"views":{"byApplianceProdId":{"map":"function(doc) {\n emit(doc.productId, [doc.brand, doc.name, doc.description])\n}"}}}

ifMatch

string

Header parameter for a conditional HTTP request matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

batch

string

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

Allowed values: ok

newEdits

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.

Default: false

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

413 -

415 -

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

index

Required *

string

Path parameter to specify the index name.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

query

Required *

string

The Lucene query to execute.

Example: name:Jane* AND active:True

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

bookmark

string

Opaque bookmark token used when paginating results.

Constraints:

• Min length: 3
• Max length: 7168
• Pattern: /^[A-Za-z0-9=_-]*$/

highlightFields

string[]

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

Constraints:

• Max items: 65535

highlightNumber

number

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.

Default: 1

highlightPostTag

string

A string that is inserted after the highlighted word in the highlights output.

Default: </em>

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^<\/.*>$/

highlightPreTag

string

A string that is inserted before the highlighted word in the highlights output.

Default: <em>

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^<.*>$/

highlightSize

number

Number of characters in each fragment for highlights.

Default: 100

includeDocs

boolean

Include the full content of the documents in the return.

Default: false

includeFields

string[]

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.

Constraints:

• Max items: 65535

limit

number

Limit the number of the returned documents to the specified number.

Example: 3

sort

string[]

Specifies 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&lt;type&gt;" or "-fieldname&lt;type&gt;" 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&lt;string&gt;", "-foo&lt;number&gt;" and ["-foo&lt;number&gt;", "bar&lt;string&gt;"]. 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.

Constraints:

• Max items: 65535

stale

string

Do not wait for the index to finish building to return results.

Allowed values: ok

counts

string[]

This field defines an array of names of string fields, for which counts are requested. The response contains counts for each unique value of this field name among the documents that match the search query. Faceting must be enabled for this parameter to function. This option is only available when making global queries.

Constraints:

• Max items: 65535

drilldown

string[][]

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.

Constraints:

• Min items: 1
• Max items: 65535

groupField

string

Field by which to group search matches. A string that contains the name of a string field. Fields containing other data such as numbers, objects, or arrays cannot be used. This option is only available when making global queries.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

groupLimit

number

Maximum group count. This field can be used only if group_field is specified. This option is only available when making global queries.

groupSort

string[]

This field defines the order of the groups in a search that uses group_field. The default sort order is relevance. This field can have the same values as the sort field, so single fields and arrays of fields are supported. This option is only available when making global queries.

Constraints:

• Max items: 65535

ranges

JsonObject

Object mapping faceted, numeric search field names to the required ranges. Each key is a field name and each value is another object defining the ranges by mapping range name keys to string values describing the numeric ranges, for example "[0 TO 10]". This option is only available when making global queries.

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

index

Required *

string

Path parameter to specify the index name.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

view

Required *

string

Path parameter to specify the map reduce view function name.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[a-z][a-z0-9_$()+\/-]*$/

attEncodingInfo

boolean

Parameter to specify whether to include the encoding information for compressed attachments. This only applies when requesting documents in the response.

Default: false

attachments

boolean

Parameter to specify whether to include attachment content in included document content or only the attachment metadata. This only applies when requesting documents in the response.

Default: false

conflicts

boolean

Parameter to specify whether to include a list of conflicted revisions in each returned document. This only applies when requesting documents in the response.

Default: false

descending

boolean

Parameter to specify whether to return the documents in descending by key order.

Default: false

includeDocs

boolean

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

Example: true

Default: false

inclusiveEnd

boolean

Parameter to specify whether to include the specified end key in the result.

Default: true

limit

number

Parameter to specify the number of returned documents to limit the result to.

Example: 10

skip

number

Parameter to specify the number of records before starting to return the results.

Default: 0

updateSeq

boolean

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

Default: false

endKey

any

Schema for any JSON type.

endKeyDocId

string

Stop returning rows at the specified document ID. No effect if using `group` or not providing end key.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

group

boolean

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

Default: false

groupLevel

number

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.

key

any

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

any[]

Parameter to specify returning only rows that match any of the specified keys. A JSON array of keys that match the key type emitted by the view function.

Example: ["examplekey"]

Constraints:

• Max items: 65535

reduce

boolean

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.

Default: true

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`.

Default: false

startKey

any

Schema for any JSON type.

startKeyDocId

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

update

string

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.

Allowed values: true, false, lazy

Default: true

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

view

Required *

string

Path parameter to specify the map reduce view function name.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[a-z][a-z0-9_$()+\/-]*$/

queries

Required *

ViewQuery[]

An array of query objects with fields for the parameters of each individual view query to be executed. The field names and their meaning are the same as the query parameters of a regular view request.

Example: [{"include_docs":true,"limit":5},{"descending":true,"skip":1}]

Constraints:

• Max items: 65535

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

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

attEncodingInfo

boolean

Parameter to specify whether to include the encoding information for compressed attachments. This only applies when requesting documents in the response.

Default: false

attachments

boolean

Parameter to specify whether to include attachment content in included document content or only the attachment metadata. This only applies when requesting documents in the response.

Default: false

conflicts

boolean

Parameter to specify whether to include a list of conflicted revisions in each returned document. This only applies when requesting documents in the response.

Default: false

descending

boolean

Parameter to specify whether to return the documents in descending by key order.

Default: false

includeDocs

boolean

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

Default: false

inclusiveEnd

boolean

Parameter to specify whether to include the specified end key in the result.

Default: true

limit

number

Parameter to specify the number of returned documents to limit the result to.

Example: 10

skip

number

Parameter to specify the number of records before starting to return the results.

Default: 0

updateSeq

boolean

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

Default: false

endKey

string

Schema for a document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

key

string

Schema for a document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

keys

string[]

Schema for a list of document IDs.

Constraints:

• Max items: 65535

startKey

string

Schema for a document ID.

Example: 0007741142412418284

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

queries

Required *

AllDocsQuery[]

An array of query objects with fields for the parameters of each individual view query to be executed. The field names and their meaning are the same as the query parameters of a regular `/_all_docs` request.

Example: [{"keys":["small-appliances:1000042","small-appliances:1000043"]},{"limit":3,"skip":2}]

Constraints:

• Min items: 1
• Max items: 65535

accept

string

The type of the response: application/json or application/octet-stream.

Allowed values: application/json, application/octet-stream

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

selector

Required *

JsonObject

JSON object describing criteria used to select documents. The selector specifies fields in the document, and provides an expression to evaluate with the field content or other data.

The selector object must: * Be structured as valid JSON. * Contain a valid query expression.

Using a selector is significantly more efficient than using a JavaScript filter function, and is the recommended option if filtering on document attributes only.

Elementary selector syntax requires you to specify one or more fields, and the corresponding values required for those fields. You can create more complex selector expressions by combining operators.

Operators are identified by the use of a dollar sign `$` prefix in the name field.

There are two core types of operators in the selector syntax:

• Combination operators: applied at the topmost level of selection. They are used to combine selectors. A combination operator takes a single argument. The argument is either another selector, or an array of selectors.
• Condition operators: are specific to a field, and are used to evaluate the value stored in that field. For instance, the basic `$eq` operator matches when the specified field contains a value that is equal to the supplied argument.

It is important for query performance to use appropriate selectors:

• Only equality operators such as `$eq`, `$gt`, `$gte`, `$lt`, and `$lte` (but not `$ne`) can be used as the basis of a query. You should include at least one of these in a selector.
• Some operators such as `$not`, `$or`, `$in`, and `$regex` cannot be answered from an index. For query selectors use these operators in conjunction with equality operators or create and use a partial index to reduce the number of documents that will need to be scanned.

See the Cloudant Docs for a list of all available combination and conditional operators.

For further reference see selector syntax.

Example: {"email_verified":{"$eq":true}}

allowFallback

boolean

Whether to allow fallback to other indexes. Default is true.

Default: true

bookmark

string

Opaque bookmark token used when paginating results.

Constraints:

• Min length: 3
• Max length: 7168
• Pattern: /^[A-Za-z0-9=_-]*$/

conflicts

boolean

A boolean value that indicates whether or not to include information about existing conflicts in the document.

executionStats

boolean

Use this option to find information about the query that was run. This information includes total key lookups, total document lookups (when `include_docs=true` is used), and total quorum document lookups (when each document replica is fetched).

fields

string[]

JSON array that uses the field syntax. Use this parameter to specify which fields of a document must be returned. If it is omitted or empty, the entire document is returned.

Example: ["_id","type","name","email"]

Constraints:

• Max items: 65535

limit

number

Maximum number of results returned. The `type: text` indexes are limited to 200 results when queried.

Example: 3

Default: 25

skip

number

Skip the first 'n' results, where 'n' is the value that is specified.

sort

JsonObject[]

The sort field contains a list of pairs, each mapping a field name to a sort direction (asc or desc). The first field name and direction pair is the topmost level of sort. The second pair, if provided, is the next level of sort. The field can be any field, using dotted notation if desired for sub-document fields.

For example in JSON: `[{"fieldName1": "desc"}, {"fieldName2.subFieldName1": "desc"}]`

When sorting with multiple fields, ensure that there is an index already defined with all the sort fields in the same order and each object in the sort array has a single key or at least one of the sort fields is included in the selector. All sorting fields must use the same sort direction, either all ascending or all descending.

Constraints:

• Max items: 65535

stable

boolean

Whether or not the view results should be returned from a "stable" set of shards.

update

string

Whether to update the index prior to returning the result.

Allowed values: false, true, lazy

Default: true

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

useIndex

string[]

Use this option to identify a specific index to answer the query, rather than letting the IBM Cloudant query planner choose an index. Specified as a two element array of design document id followed by index name, for example `["my_design_doc", "my_index"]`.

It’s recommended to specify indexes explicitly in your queries to prevent existing queries being affected by new indexes that might get added later.

If the specified index doesn't exist or can't answer the query then the server ignores the value and answers using another index or a full scan of all documents. To change this behavior set `allow_fallback` to `false` and the server responds instead with a `400` status code if the requested index is unsuitable to answer the query.

Constraints:

• Min items: 2
• Max items: 2

r

number

The read quorum that is needed for the result. The value defaults to 1, in which case the document that was found in the index is returned. If set to a higher value, each document is read from at least that many replicas before it is returned in the results. The request will take more time than using only the document that is stored locally with the index.

Default: 1

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

selector

Required *

JsonObject

JSON object describing criteria used to select documents. The selector specifies fields in the document, and provides an expression to evaluate with the field content or other data.

The selector object must: * Be structured as valid JSON. * Contain a valid query expression.

Using a selector is significantly more efficient than using a JavaScript filter function, and is the recommended option if filtering on document attributes only.

Elementary selector syntax requires you to specify one or more fields, and the corresponding values required for those fields. You can create more complex selector expressions by combining operators.

Operators are identified by the use of a dollar sign `$` prefix in the name field.

There are two core types of operators in the selector syntax:

• Combination operators: applied at the topmost level of selection. They are used to combine selectors. A combination operator takes a single argument. The argument is either another selector, or an array of selectors.
• Condition operators: are specific to a field, and are used to evaluate the value stored in that field. For instance, the basic `$eq` operator matches when the specified field contains a value that is equal to the supplied argument.

It is important for query performance to use appropriate selectors:

• Only equality operators such as `$eq`, `$gt`, `$gte`, `$lt`, and `$lte` (but not `$ne`) can be used as the basis of a query. You should include at least one of these in a selector.
• Some operators such as `$not`, `$or`, `$in`, and `$regex` cannot be answered from an index. For query selectors use these operators in conjunction with equality operators or create and use a partial index to reduce the number of documents that will need to be scanned.

See the Cloudant Docs for a list of all available combination and conditional operators.

For further reference see selector syntax.

Example: {"email_verified":{"$eq":true}}

allowFallback

boolean

Whether to allow fallback to other indexes. Default is true.

Default: true

bookmark

string

Opaque bookmark token used when paginating results.

Constraints:

• Min length: 3
• Max length: 7168
• Pattern: /^[A-Za-z0-9=_-]*$/

conflicts

boolean

A boolean value that indicates whether or not to include information about existing conflicts in the document.

executionStats

boolean

Use this option to find information about the query that was run. This information includes total key lookups, total document lookups (when `include_docs=true` is used), and total quorum document lookups (when each document replica is fetched).

fields

string[]

JSON array that uses the field syntax. Use this parameter to specify which fields of a document must be returned. If it is omitted or empty, the entire document is returned.

Example: ["_id","type","name","email"]

Constraints:

• Max items: 65535

limit

number

Maximum number of results returned. The `type: text` indexes are limited to 200 results when queried.

Example: 3

Default: 25

skip

number

Skip the first 'n' results, where 'n' is the value that is specified.

sort

JsonObject[]

The sort field contains a list of pairs, each mapping a field name to a sort direction (asc or desc). The first field name and direction pair is the topmost level of sort. The second pair, if provided, is the next level of sort. The field can be any field, using dotted notation if desired for sub-document fields.

For example in JSON: `[{"fieldName1": "desc"}, {"fieldName2.subFieldName1": "desc"}]`

When sorting with multiple fields, ensure that there is an index already defined with all the sort fields in the same order and each object in the sort array has a single key or at least one of the sort fields is included in the selector. All sorting fields must use the same sort direction, either all ascending or all descending.

Constraints:

• Max items: 65535

stable

boolean

Whether or not the view results should be returned from a "stable" set of shards.

update

string

Whether to update the index prior to returning the result.

Allowed values: false, true, lazy

Default: true

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

useIndex

string[]

Use this option to identify a specific index to answer the query, rather than letting the IBM Cloudant query planner choose an index. Specified as a two element array of design document id followed by index name, for example `["my_design_doc", "my_index"]`.

It’s recommended to specify indexes explicitly in your queries to prevent existing queries being affected by new indexes that might get added later.

If the specified index doesn't exist or can't answer the query then the server ignores the value and answers using another index or a full scan of all documents. To change this behavior set `allow_fallback` to `false` and the server responds instead with a `400` status code if the requested index is unsuitable to answer the query.

Constraints:

• Min items: 2
• Max items: 2

r

number

The read quorum that is needed for the result. The value defaults to 1, in which case the document that was found in the index is returned. If set to a higher value, each document is read from at least that many replicas before it is returned in the results. The request will take more time than using only the document that is stored locally with the index.

Default: 1

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

index

Required *

IndexDefinition

Schema for a `json` or `text` query index definition. Indexes of type `text` have additional configuration properties that do not apply to `json` indexes, these are:

• `default_analyzer` - the default text analyzer to use
• `default_field` - whether to index the text in all document fields and what analyzer to use for that purpose.

Example: {"fields":[{"name":"asc"}]}

ddoc

string

Specifies the design document name in which the index will be created. The design document name is the design document ID excluding the `_design/` prefix.

Example: json-index

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_design\/].*$/

name

string

name.

Example: getUserByName

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].*$/

partitioned

boolean

The default value is `true` for databases with `partitioned: true` and `false` otherwise. For databases with `partitioned: false` if this option is specified the value must be `false`.

type

string

Schema for the type of an index.

Example: json

Allowed values: json, special, text

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

type

Required *

string

Path parameter to specify the index type.

Allowed values: json, special, text

index

Required *

string

Path parameter to specify the index name.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

batch

string

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

Allowed values: ok

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

accept

string

The type of the response: application/json, multipart/mixed, multipart/related, or application/octet-stream.

Allowed values: application/json, multipart/mixed, multipart/related, application/octet-stream

Default: application/json

ifNoneMatch

string

Header parameter for a conditional HTTP request not matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

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.

Default: false

attEncodingInfo

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.

Default: false

localSeq

boolean

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

Default: false

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

document

Required *

Document | NodeJS.ReadableStream | Buffer

HTTP request body for Document operations.

Example: {"_id":"exampleid","brand":"Foo","colours":["red","green","black","blue"],"description":"Slim Colourful Design Electronic Cooking Appliance for ...","image":"assets/img/0gmsnghhew.jpg","keywords":["Foo","Scales","Weight","Digital","Kitchen"],"name":"Digital Kitchen Scales","price":14.99,"productId":"1000042","taxonomy":["Home","Kitchen","Small Appliances"],"type":"product"}

contentType

string

The type of the input.

Allowed values: application/json, multipart/mixed, multipart/related, application/octet-stream

batch

string

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

Allowed values: ok

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

partitionKey

Required *

string

Path parameter to specify the database partition key.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_:][^:]*$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

partitionKey

Required *

string

Path parameter to specify the database partition key.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_:][^:]*$/

attEncodingInfo

boolean

Parameter to specify whether to include the encoding information for compressed attachments. This only applies when requesting documents in the response.

Default: false

attachments

boolean

Parameter to specify whether to include attachment content in included document content or only the attachment metadata. This only applies when requesting documents in the response.

Default: false

conflicts

boolean

Parameter to specify whether to include a list of conflicted revisions in each returned document. This only applies when requesting documents in the response.

Default: false

descending

boolean

Parameter to specify whether to return the documents in descending by key order.

Default: false

includeDocs

boolean

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

Default: false

inclusiveEnd

boolean

Parameter to specify whether to include the specified end key in the result.

Default: true

limit

number

Parameter to specify the number of returned documents to limit the result to.

Example: 10

skip

number

Parameter to specify the number of records before starting to return the results.

Default: 0

updateSeq

boolean

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

Default: false

endKey

string

Schema for a document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

key

string

Schema for a document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

keys

string[]

Schema for a list of document IDs.

Constraints:

• Max items: 65535

startKey

string

Schema for a document ID.

Example: 0007741142412418284

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

Query a database partition search index

POST /{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.

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

partitionKey

Required *

string

Path parameter to specify the database partition key.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_:][^:]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

index

Required *

string

Path parameter to specify the index name.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

query

Required *

string

The Lucene query to execute.

Example: name:Jane* AND active:True

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

bookmark

string

Opaque bookmark token used when paginating results.

Constraints:

• Min length: 3
• Max length: 7168
• Pattern: /^[A-Za-z0-9=_-]*$/

highlightFields

string[]

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

Constraints:

• Max items: 65535

highlightNumber

number

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.

Default: 1

highlightPostTag

string

A string that is inserted after the highlighted word in the highlights output.

Default: </em>

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^<\/.*>$/

highlightPreTag

string

A string that is inserted before the highlighted word in the highlights output.

Default: <em>

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^<.*>$/

highlightSize

number

Number of characters in each fragment for highlights.

Default: 100

includeDocs

boolean

Include the full content of the documents in the return.

Default: false

includeFields

string[]

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.

Constraints:

• Max items: 65535

limit

number

Limit the number of the returned documents to the specified number.

Example: 3

sort

string[]

Specifies 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&lt;type&gt;" or "-fieldname&lt;type&gt;" 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&lt;string&gt;", "-foo&lt;number&gt;" and ["-foo&lt;number&gt;", "bar&lt;string&gt;"]. 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.

Constraints:

• Max items: 65535

stale

string

Do not wait for the index to finish building to return results.

Allowed values: ok

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

partitionKey

Required *

string

Path parameter to specify the database partition key.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_:][^:]*$/

ddoc

Required *

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

view

Required *

string

Path parameter to specify the map reduce view function name.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[a-z][a-z0-9_$()+\/-]*$/

attEncodingInfo

boolean

Parameter to specify whether to include the encoding information for compressed attachments. This only applies when requesting documents in the response.

Default: false

attachments

boolean

Parameter to specify whether to include attachment content in included document content or only the attachment metadata. This only applies when requesting documents in the response.

Default: false

conflicts

boolean

Parameter to specify whether to include a list of conflicted revisions in each returned document. This only applies when requesting documents in the response.

Default: false

descending

boolean

Parameter to specify whether to return the documents in descending by key order.

Default: false

includeDocs

boolean

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

Example: true

Default: false

inclusiveEnd

boolean

Parameter to specify whether to include the specified end key in the result.

Default: true

limit

number

Parameter to specify the number of returned documents to limit the result to.

Example: 10

skip

number

Parameter to specify the number of records before starting to return the results.

Default: 0

updateSeq

boolean

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

Default: false

endKey

any

Schema for any JSON type.

endKeyDocId

string

Stop returning rows at the specified document ID. No effect if using `group` or not providing end key.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

group

boolean

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

Default: false

groupLevel

number

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.

key

any

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

any[]

Parameter to specify returning only rows that match any of the specified keys. A JSON array of keys that match the key type emitted by the view function.

Example: ["examplekey"]

Constraints:

• Max items: 65535

reduce

boolean

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.

Default: true

startKey

any

Schema for any JSON type.

startKeyDocId

string

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

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^([^_]|_(design|local)\/).+$/

update

string

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.

Allowed values: true, false, lazy

Default: true

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

partitionKey

Required *

string

Path parameter to specify the database partition key.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_:][^:]*$/

selector

Required *

JsonObject

JSON object describing criteria used to select documents. The selector specifies fields in the document, and provides an expression to evaluate with the field content or other data.

The selector object must: * Be structured as valid JSON. * Contain a valid query expression.

Using a selector is significantly more efficient than using a JavaScript filter function, and is the recommended option if filtering on document attributes only.

Elementary selector syntax requires you to specify one or more fields, and the corresponding values required for those fields. You can create more complex selector expressions by combining operators.

Operators are identified by the use of a dollar sign `$` prefix in the name field.

There are two core types of operators in the selector syntax:

• Combination operators: applied at the topmost level of selection. They are used to combine selectors. A combination operator takes a single argument. The argument is either another selector, or an array of selectors.
• Condition operators: are specific to a field, and are used to evaluate the value stored in that field. For instance, the basic `$eq` operator matches when the specified field contains a value that is equal to the supplied argument.

It is important for query performance to use appropriate selectors:

• Only equality operators such as `$eq`, `$gt`, `$gte`, `$lt`, and `$lte` (but not `$ne`) can be used as the basis of a query. You should include at least one of these in a selector.
• Some operators such as `$not`, `$or`, `$in`, and `$regex` cannot be answered from an index. For query selectors use these operators in conjunction with equality operators or create and use a partial index to reduce the number of documents that will need to be scanned.

See the Cloudant Docs for a list of all available combination and conditional operators.

For further reference see selector syntax.

Example: {"type":{"$eq":"product"}}

allowFallback

boolean

Whether to allow fallback to other indexes. Default is true.

Default: true

bookmark

string

Opaque bookmark token used when paginating results.

Constraints:

• Min length: 3
• Max length: 7168
• Pattern: /^[A-Za-z0-9=_-]*$/

conflicts

boolean

A boolean value that indicates whether or not to include information about existing conflicts in the document.

executionStats

boolean

Use this option to find information about the query that was run. This information includes total key lookups, total document lookups (when `include_docs=true` is used), and total quorum document lookups (when each document replica is fetched).

fields

string[]

JSON array that uses the field syntax. Use this parameter to specify which fields of a document must be returned. If it is omitted or empty, the entire document is returned.

Example: ["productId","name","description"]

Constraints:

• Max items: 65535

limit

number

Maximum number of results returned. The `type: text` indexes are limited to 200 results when queried.

Default: 25

skip

number

Skip the first 'n' results, where 'n' is the value that is specified.

sort

JsonObject[]

The sort field contains a list of pairs, each mapping a field name to a sort direction (asc or desc). The first field name and direction pair is the topmost level of sort. The second pair, if provided, is the next level of sort. The field can be any field, using dotted notation if desired for sub-document fields.

For example in JSON: `[{"fieldName1": "desc"}, {"fieldName2.subFieldName1": "desc"}]`

When sorting with multiple fields, ensure that there is an index already defined with all the sort fields in the same order and each object in the sort array has a single key or at least one of the sort fields is included in the selector. All sorting fields must use the same sort direction, either all ascending or all descending.

Constraints:

• Max items: 65535

stable

boolean

Whether or not the view results should be returned from a "stable" set of shards.

update

string

Whether to update the index prior to returning the result.

Allowed values: false, true, lazy

Default: true

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

useIndex

string[]

Use this option to identify a specific index to answer the query, rather than letting the IBM Cloudant query planner choose an index. Specified as a two element array of design document id followed by index name, for example `["my_design_doc", "my_index"]`.

It’s recommended to specify indexes explicitly in your queries to prevent existing queries being affected by new indexes that might get added later.

If the specified index doesn't exist or can't answer the query then the server ignores the value and answers using another index or a full scan of all documents. To change this behavior set `allow_fallback` to `false` and the server responds instead with a `400` status code if the requested index is unsuitable to answer the query.

Constraints:

• Min items: 2
• Max items: 2

Response

200 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

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.

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.

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

partitionKey

Required *

string

Path parameter to specify the database partition key.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_:][^:]*$/

selector

Required *

JsonObject

JSON object describing criteria used to select documents. The selector specifies fields in the document, and provides an expression to evaluate with the field content or other data.

The selector object must: * Be structured as valid JSON. * Contain a valid query expression.

Using a selector is significantly more efficient than using a JavaScript filter function, and is the recommended option if filtering on document attributes only.

Elementary selector syntax requires you to specify one or more fields, and the corresponding values required for those fields. You can create more complex selector expressions by combining operators.

Operators are identified by the use of a dollar sign `$` prefix in the name field.

There are two core types of operators in the selector syntax:

• Combination operators: applied at the topmost level of selection. They are used to combine selectors. A combination operator takes a single argument. The argument is either another selector, or an array of selectors.
• Condition operators: are specific to a field, and are used to evaluate the value stored in that field. For instance, the basic `$eq` operator matches when the specified field contains a value that is equal to the supplied argument.

It is important for query performance to use appropriate selectors:

• Only equality operators such as `$eq`, `$gt`, `$gte`, `$lt`, and `$lte` (but not `$ne`) can be used as the basis of a query. You should include at least one of these in a selector.
• Some operators such as `$not`, `$or`, `$in`, and `$regex` cannot be answered from an index. For query selectors use these operators in conjunction with equality operators or create and use a partial index to reduce the number of documents that will need to be scanned.

See the Cloudant Docs for a list of all available combination and conditional operators.

For further reference see selector syntax.

Example: {"type":{"$eq":"product"}}

allowFallback

boolean

Whether to allow fallback to other indexes. Default is true.

Default: true

bookmark

string

Opaque bookmark token used when paginating results.

Constraints:

• Min length: 3
• Max length: 7168
• Pattern: /^[A-Za-z0-9=_-]*$/

conflicts

boolean

A boolean value that indicates whether or not to include information about existing conflicts in the document.

executionStats

boolean

Use this option to find information about the query that was run. This information includes total key lookups, total document lookups (when `include_docs=true` is used), and total quorum document lookups (when each document replica is fetched).

fields

string[]

JSON array that uses the field syntax. Use this parameter to specify which fields of a document must be returned. If it is omitted or empty, the entire document is returned.

Example: ["productId","name","description"]

Constraints:

• Max items: 65535

limit

number

Maximum number of results returned. The `type: text` indexes are limited to 200 results when queried.

Default: 25

skip

number

Skip the first 'n' results, where 'n' is the value that is specified.

sort

JsonObject[]

The sort field contains a list of pairs, each mapping a field name to a sort direction (asc or desc). The first field name and direction pair is the topmost level of sort. The second pair, if provided, is the next level of sort. The field can be any field, using dotted notation if desired for sub-document fields.

For example in JSON: `[{"fieldName1": "desc"}, {"fieldName2.subFieldName1": "desc"}]`

When sorting with multiple fields, ensure that there is an index already defined with all the sort fields in the same order and each object in the sort array has a single key or at least one of the sort fields is included in the selector. All sorting fields must use the same sort direction, either all ascending or all descending.

Constraints:

• Max items: 65535

stable

boolean

Whether or not the view results should be returned from a "stable" set of shards.

update

string

Whether to update the index prior to returning the result.

Allowed values: false, true, lazy

Default: true

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^.+$/

useIndex

string[]

Use this option to identify a specific index to answer the query, rather than letting the IBM Cloudant query planner choose an index. Specified as a two element array of design document id followed by index name, for example `["my_design_doc", "my_index"]`.

It’s recommended to specify indexes explicitly in your queries to prevent existing queries being affected by new indexes that might get added later.

If the specified index doesn't exist or can't answer the query then the server ignores the value and answers using another index or a full scan of all documents. To change this behavior set `allow_fallback` to `false` and the server responds instead with a `400` status code if the requested index is unsuitable to answer the query.

Constraints:

• Min items: 2
• Max items: 2

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

documentRevisions

Required *

JsonObject

HTTP request body for operations with Document revisions.

Example: {"order00077":["3-b06fcd1c1c9e0ec7c480ee8aa467bf3b","3-0e871ef78849b0c206091f1a7af6ec41"]}

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

ifMatch

string

Header parameter for a conditional HTTP request matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

batch

string

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

Allowed values: ok

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

ifNoneMatch

string

Header parameter for a conditional HTTP request not matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

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.

Default: false

attEncodingInfo

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.

Default: false

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.

Default: false

deletedConflicts

boolean

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

Default: false

latest

boolean

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

Default: false

localSeq

boolean

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

Default: false

meta

boolean

Query parameter to specify whether to include document meta information. Acts the same as specifying all of the conflicts, deleted_conflicts and open_revs query parameters.

Default: false

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

revs

boolean

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

Default: false

revsInfo

boolean

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

Default: false

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

ifNoneMatch

string

Header parameter for a conditional HTTP request not matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

latest

boolean

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

Default: false

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

Response

200 -

304 -

400 -

401 -

402 -

403 -

404 -

408 -

410 -

429 -

500 -

502 -

503 -

504 -

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

document

Required *

Document | NodeJS.ReadableStream | Buffer

HTTP request body for Document operations.

Example: {"_id":"exampleid","brand":"Foo","colours":["red","green","black","blue"],"description":"Slim Colourful Design Electronic Cooking Appliance for ...","image":"assets/img/0gmsnghhew.jpg","keywords":["Foo","Scales","Weight","Digital","Kitchen"],"name":"Digital Kitchen Scales","price":14.99,"productId":"1000042","taxonomy":["Home","Kitchen","Small Appliances"],"type":"product"}

contentType

string

The type of the input.

Allowed values: application/json, multipart/mixed, multipart/related, application/octet-stream

Default: application/json

ifMatch

string

Header parameter for a conditional HTTP request matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

batch

string

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

Allowed values: ok

newEdits

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.

Default: false

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

413 -

415 -

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

attachmentName

Required *

string

Path parameter to specify the attachment name.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].*$/

ifMatch

string

Header parameter for a conditional HTTP request matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

batch

string

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

Allowed values: ok

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

attachmentName

Required *

string

Path parameter to specify the attachment name.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].*$/

accept

string

The type of the response: /.

ifMatch

string

Header parameter for a conditional HTTP request matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

ifNoneMatch

string

Header parameter for a conditional HTTP request not matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

range

string

Header parameter to specify the byte range for a request. This allows the implementation of resumable downloads and skippable streams. This is available for all attachments inside CouchDB.

Constraints:

• Min length: 7
• Max length: 23
• Pattern: /^bytes=(?:-\\d+)|(?:\\d+-)|(?:\\d+-\\d+)(?:,\\d+-\\d+)*$/

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

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

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

attachmentName

Required *

string

Path parameter to specify the attachment name.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].*$/

ifMatch

string

Header parameter for a conditional HTTP request matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

ifNoneMatch

string

Header parameter for a conditional HTTP request not matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

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.

• cloudantnosqldb.data-document.write

Auditing

Calling this method generates the following auditing event.

• cloudantnosqldb.data-document.write

Request

Parameters

db

Required *

string

Path parameter to specify the database name.

Constraints:

• Min length: 1
• Max length: 238
• Pattern: /^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$|^[a-z][a-z0-9_$()+\/-]*$/

docId

Required *

string

Path parameter to specify the document ID.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].+$/

attachmentName

Required *

string

Path parameter to specify the attachment name.

Constraints:

• Min length: 1
• Max length: 7168
• Pattern: /^[^_].*$/

attachment

Required *

NodeJS.ReadableStream | Buffer

HTTP request body for attachment operations.

Example: This appliance includes...

contentType

Required *

string

Content-Type of the attachment.

Default: application/octet-stream

ifMatch

string

Header parameter for a conditional HTTP request matching an ETag.

Constraints:

• Min length: 26
• Max length: 45
• Pattern: /^\"[A-Za-z0-9+\/]{2,24}={0,3}\"$|^\"[1-9]\\d{0,9}-[\\da-f]{32}\"$|^\"[0-9A-Z]{25}\"$/

rev

string

Query parameter to specify a document revision.

Constraints:

• Min length: 34
• Max length: 43
• Pattern: /^[1-9]\\d{0,9}-[\\da-f]{32}$/

Response

201 -

202 -

400 -

401 -

402 -

403 -

404 -

408 -

409 -

410 -

413 -

415 -

429 -

500 -

502 -

503 -

504 -

507 -