GET /
When you access the root of an instance, IBM Cloudant returns meta-information about the instance. The response includes a JSON structure that contains information about the server, including a welcome message and the server's version.
Tip: The authentication for this endpoint is only enforced when using IAM.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.account-meta-info.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve list of running tasks
GET /_active_tasks
Lists running tasks, including the task type, name, status, and process ID. The result includes a JSON array of the currently running tasks, with each task described as a single object. Depending on the operation type, the set of response object fields might be different.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.account-active-tasks.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.account-active-tasks.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Query a list of all database names in the instance
GET /_all_dbs
Query to retrieve a list of database names from the instance.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.account-all-dbs.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.account-all-dbs.read
Request
Path Parameters
Query Parameters
descending
boolean
Query parameter to specify whether to return rows in descending by key order.
end_key
string
Query parameter to specify to stop returning records when the specified key is reached. String representation of any JSON type that matches the key type emitted by the view function.
limit
integer
Query parameter to specify the number of returned documents to limit the result to.
skip
integer
Query parameter to specify the number of records before starting to return the results.
start_key
string
Query parameter to specify to start returning records from the specified key. String representation of any JSON type that matches the key type emitted by the view function.
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Query information about multiple databases
POST /_dbs_info
This operation enables you to request information about multiple databases in a single request, instead of issuing multiple `GET /{db}` requests. It returns a list that contains an information object for each database specified in the request.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.account-dbs-info.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.account-dbs-info.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Retrieve cluster membership information
GET /_membership
Displays the nodes that are part of the cluster as `cluster_nodes`. The field, `all_nodes`, displays all nodes this node knows about, including the ones that are part of the cluster. This endpoint is useful when you set up a cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.cluster-membership.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.cluster-membership.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Cancel a persistent replication
DELETE /_replicator/{doc_id}
Cancels a replication by deleting the document that describes it from the `_replicator` database.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.replication.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.replication.write
Request
Path Parameters
Query Parameters
batch
string
Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.
rev
Query parameter to specify a document revision.
Response
200 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
409 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve the configuration for a persistent replication
GET /_replicator/{doc_id}
Retrieves a replication document from the `_replicator` database to view the configuration of the replication. The status of the replication is no longer recorded in the document but can be checked via the replication scheduler.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.replication.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.replication.read
Request
Path Parameters
Query Parameters
attachments
boolean
Query parameter to specify whether to include attachment content in the response. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
att_encoding_info
boolean
Query parameter to specify whether to include the encoding information for compressed attachments. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
atts_since
array
Query parameter to specify whether to include attachments only since specified revisions. Note this does not include the attachments for the specified revisions.
conflicts
boolean
Query parameter to specify whether to include a list of conflicted revisions in each returned document. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
deleted_conflicts
boolean
Query parameter to specify whether to include a list of deleted conflicted revisions in the `_deleted_conflicts` property of the returned document.
latest
boolean
Query parameter to specify whether to force retrieving latest leaf revision, no matter what rev was requested.
local_seq
boolean
Query parameter to specify whether to include the last update sequence for the document.
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.
open_revs
array
Query parameter to specify leaf revisions to retrieve. Additionally, it accepts a value of `all` to return all leaf revisions.
rev
Query parameter to specify a document revision.
revs
boolean
Query parameter to specify whether to include a list of all known document revisions.
revs_info
boolean
Query parameter to specify whether to includes detailed information for all known document revisions.
Response
200 -
304 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve the HTTP headers for a persistent replication
HEAD /_replicator/{doc_id}
Retrieves the HTTP headers containing minimal amount of information about the specified replication document from the `_replicator` database. The method supports the same query arguments as the `GET /_replicator/{doc_id}` method, but only headers like content length and the revision (ETag header) are returned.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.replication.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.replication.read
Request
Path Parameters
Query Parameters
Response
200 -
304 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Create or modify a persistent replication
PUT /_replicator/{doc_id}
Creates or modifies a document in the `_replicator` database to start a new replication or to edit an existing replication.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.replication.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.replication.write
Request
Request Body
Path Parameters
Query Parameters
batch
string
Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.
new_edits
boolean
Query parameter to specify whether to prevent insertion of conflicting document revisions. If false, a well-formed _rev must be included in the document. False is used by the replicator to insert documents into the target database even if that leads to the creation of conflicts.
Avoid using this parameter, since this option applies document revisions without checking for conflicts, so it is very easy to accidentally end up with a large number of conflicts.
rev
Query parameter to specify a document revision.
Response
201 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
409 -
410 -
412 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Retrieve replication scheduler documents
GET /_scheduler/docs
Lists replication documents, including information about all documents, even the ones in a completed or failed state. For each document, the endpoint returns the document ID, database, replication ID, source and target, and other information.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.replication-scheduler.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.replication-scheduler.read
Request
Path Parameters
Query Parameters
limit
integer
Query parameter to specify the number of returned documents to limit the result to.
skip
integer
Query parameter to specify the number of records before starting to return the results.
states
array
Query parameter to include only replication documents in the specified states. String must be a comma-delimited string.
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve a replication scheduler document
GET /_scheduler/docs/_replicator/{doc_id}
Retrieves information about a replication document from the replicator database. The endpoint returns the document ID, database, replication ID, source and target, and other information.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.replication-scheduler.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.replication-scheduler.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve replication scheduler jobs
GET /_scheduler/jobs
Retrieves information about replications that were created via `/_replicate` endpoint, as well as those created from replication documents. It doesn't include replications that completed or failed to start because replication documents were malformed. Each job description includes source and target information, replication ID, history of recent events, and other information.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.replication-scheduler.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.replication-scheduler.read
Request
Path Parameters
Query Parameters
limit
integer
Query parameter to specify the number of returned jobs to limit the result to.
skip
integer
Query parameter to specify the number of records before starting to return the results.
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve a replication scheduler job
GET /_scheduler/jobs/{job_id}
Retrieves the state of a single replication task based on its replication ID
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.replication-scheduler.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.replication-scheduler.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve the HTTP headers for a replication scheduler job
HEAD /_scheduler/jobs/{job_id}
Returns the HTTP headers that contain a minimal amount of information about the specified replication task. Only the header information is returned.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.replication-scheduler.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.replication-scheduler.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Query tokenization of sample text
POST /_search_analyze
Returns the results of analyzer tokenization of the provided sample text. This endpoint can be used for testing analyzer tokenization.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.account-search-analyze.execute
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.account-search-analyze.execute
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
GET /_up
Confirms that the server is up, running, and ready to respond to requests. If the cluster is unavailable the endpoint returns a `503` response code.
Tip: The authentication for this endpoint is only enforced when using IAM.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.account-up.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
GET /_uuids
Requests one or more Universally Unique Identifiers (UUIDs) from the instance. The response is a JSON object that provides a list of UUIDs.
Tip: The authentication for this endpoint is only enforced when using IAM.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.cluster-uuids.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.cluster-uuids.read
Request
Path Parameters
Query Parameters
count
integer
Query parameter to specify the number of UUIDs to return.
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Delete a database
DELETE /{db}
Deletes the specified database and all documents and attachments contained within it. To avoid deleting a database, the server responds with a 400 HTTP status code when the request URL includes a `?rev=` parameter. This response suggests that a user wanted to delete a document but forgot to add the document ID to the URL.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.database.delete
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.database.delete
Request
Path Parameters
Query Parameters
Response
200 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve information about a database
GET /{db}
Retrieve detailed information about the database.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.database-info.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.database-info.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve the HTTP headers for a database
HEAD /{db}
Returns the HTTP headers that contain a minimal amount of information about the specified database. Since the response body is empty, using the HEAD method is a lightweight way to check if the database exists or not.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.database-info.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.database-info.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
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.writecloudantnosqldb.design-document.writecloudantnosqldb.local-document.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.data-document.writecloudantnosqldb.design-document.writecloudantnosqldb.local-document.write
Request
Request Body
Path Parameters
Query Parameters
batch
string
Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.
Response
201 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
409 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
507 -
Create a database
PUT /{db}
Create a new database with the requested properties.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.database.create
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.database.create
Request
Path Parameters
Query Parameters
partitioned
boolean
Query parameter to specify whether to enable database partitions when creating a database.
Before using read the FAQs to understand the limitations and appropriate use cases.
n
The number of replicas of the database in the cluster. The default is 3, unless overridden in the `cluster config`.
q
The number of shards in the database. Each shard is a partition of the hash value range. Cloudant recommends using the default value for most databases. However, if your database is expected to be larger than 250 GB or have a lot of indexes, you may need to adjust the settings. In these cases, it's best to reach out to IBM Cloudant customer support for guidance on how to meet your specific needs and requirements.
Response
201 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
412 -
415 -
429 -
500 -
502 -
503 -
504 -
Query a list of all documents in a database
POST /{db}/_all_docs
Queries the primary index (all document IDs). The results that match the request body parameters are returned in a JSON object, including a list of matching documents with basic contents, such as the ID and revision. When no request body parameters are specified, results for all documents in the database are returned. Optionally, document content or additional metadata can be included in the response.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Multi-query the list of all documents in a database
POST /{db}/_all_docs/queries
Runs multiple queries using the primary index (all document IDs). Returns a JSON object that contains a list of result objects, one for each query, with a structure equivalent to that of a single `_all_docs` request. This enables you to request multiple queries in a single request, in place of multiple `POST /{db}/_all_docs` requests.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Bulk modify multiple documents in a database
POST /{db}/_bulk_docs
The bulk document API allows you to create, update, and delete multiple documents at the same time within a single request. The basic operation is similar to creating, updating, or deleting a single document, except that you batch the document structure and information.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.data-document.writecloudantnosqldb.design-document.writecloudantnosqldb.local-document.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.data-document.writecloudantnosqldb.design-document.writecloudantnosqldb.local-document.write
Request
Request Body
Path Parameters
Query Parameters
Response
201 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
507 -
Bulk query revision information for multiple documents
POST /{db}/_bulk_get
Fetch specific revisions or revision histories for multiple documents in bulk as replicators do.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
attachments
boolean
Query parameter to specify whether to include attachment content in the response. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
att_encoding_info
boolean
Query parameter to specify whether to include the encoding information for compressed attachments. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
latest
boolean
Query parameter to specify whether to force retrieving latest leaf revision, no matter what rev was requested.
revs
boolean
Query parameter to specify whether to include a list of all known document revisions.
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
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
Request Body
Path Parameters
Query Parameters
att_encoding_info
boolean
Query parameter to specify whether to include the encoding information for compressed attachments. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
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.
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.
descending
boolean
Query parameter to specify whether to return changes in the descending order with most recent change first. The `since` parameter has no effect when using descending order.
feed
string
Query parameter to specify the changes feed type.
filter
string
Query parameter to specify a filter to emit only specific events from the changes stream.
The built-in filter types are: * `_design` - Returns only changes to design documents. * `_doc_ids` - Returns changes for documents with an ID matching one specified in `doc_ids` request body parameter. (`POST` only) * `_selector` - Returns changes for documents that match the `selector` request body parameter. The selector syntax is the same as used for `_find`. (`POST` only) * `_view` - Returns changes for documents that match an existing map function in the view specified by the query parameter `view`.
Additionally, the value can be the name of a JS filter function from a design document. For example: `design_doc/filtername`.
Note: For better performance use the built-in `_selector`, `_design` or `_doc_ids` filters rather than JS based `_view` or design document filters. If you need to pass values to change the filtered content use the `_selector` filter type.
heartbeat
integer
Query parameter to specify the period in milliseconds after which an empty line is sent in the results. Off by default and only applicable for `continuous` and `eventsource` feeds. Overrides any timeout to keep the feed alive indefinitely. May also be `true` to use a value of `60000`.
Note: Delivery of heartbeats cannot be relied on at specific intervals. If your application runs in an environment where idle network connections may break, `heartbeat` is not suitable as a keepalive mechanism. Instead, consider one of the following options: * Use the `timeout` parameter with a value that is compatible with your network environment. * Switch to scheduled usage of one of the non-continuous changes feed types (`normal` or `longpoll`). * Use TCP keepalive.
include_docs
boolean
Query parameter to specify whether to include the full content of the documents in the response.
last_event_id
Query parameter to specify the ID of the last events received by the server on a previous connection. Alias of `Last-Event-ID` header.
limit
integer
Query parameter to specify the number of returned documents to limit the result to.
seq_interval
integer
Query parameter to specify that the update seq should only be calculated with every Nth result returned. When fetching changes in a batch, setting <code>seq_interval=<batch size></code>, where <batch size> is the number of results requested per batch, load can be reduced on the source database as computing the seq value across many shards (especially in highly-sharded databases) is expensive.
since
Query parameter to specify to start the results from the change immediately after the given update sequence. Possible values are: * `0` for all available changes (default). * `now` for future changes. * A valid update sequence, for example, from the `seq` value of a change received before.
style
string
Query parameter to specify how many revisions are returned in the changes array. The default, `main_only`, will only return the current "winning" revision; all_docs will return all leaf revisions (including conflicts and deleted former conflicts).
timeout
integer
Query parameter to specify the maximum period in milliseconds to wait for a change before the response is sent, even if there are no results. Only applicable for `longpoll` or `continuous` feeds. Default value is specified by `httpd/changes_timeout` configuration option. Note that `60000` value is also the default maximum timeout to prevent undetected dead connections.
view
string
Query parameter to specify a view function as a filter. Documents pass the filter if the view's map function emits at least one record for them.
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Delete a design document
DELETE /{db}/_design/{ddoc}
Marks the specified design document as deleted by adding a `_deleted` field with the value `true`. Documents with this field are not returned with requests but stay in the database. You must supply the current (latest) revision, either by using the `rev` parameter or by using the `If-Match` header to specify the revision.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.design-document.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.design-document.write
Request
Path Parameters
Query Parameters
batch
string
Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.
rev
Query parameter to specify a document revision.
Response
200 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
409 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve a design document
GET /{db}/_design/{ddoc}
Returns design document with the specified `doc_id` from the specified database. Unless you request a specific revision, the current revision of the design document is always returned.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Path Parameters
Query Parameters
attachments
boolean
Query parameter to specify whether to include attachment content in the response. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
att_encoding_info
boolean
Query parameter to specify whether to include the encoding information for compressed attachments. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
atts_since
array
Query parameter to specify whether to include attachments only since specified revisions. Note this does not include the attachments for the specified revisions.
conflicts
boolean
Query parameter to specify whether to include a list of conflicted revisions in each returned document. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
deleted_conflicts
boolean
Query parameter to specify whether to include a list of deleted conflicted revisions in the `_deleted_conflicts` property of the returned document.
latest
boolean
Query parameter to specify whether to force retrieving latest leaf revision, no matter what rev was requested.
local_seq
boolean
Query parameter to specify whether to include the last update sequence for the document.
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.
open_revs
array
Query parameter to specify leaf revisions to retrieve. Additionally, it accepts a value of `all` to return all leaf revisions.
rev
Query parameter to specify a document revision.
revs
boolean
Query parameter to specify whether to include a list of all known document revisions.
revs_info
boolean
Query parameter to specify whether to includes detailed information for all known document revisions.
Response
200 -
304 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve the HTTP headers for a design document
HEAD /{db}/_design/{ddoc}
This method supports the same query arguments as the `GET /{db}/_design/{ddoc}` method, but the results include only the header information (including design document size, and the revision as an ETag). The ETag header shows the current revision for the requested design document, and if you requested the design document in full, the Content-Length specifies the length of the data. If you add any of the query arguments, then the resulting HTTP headers correspond to what is returned for the equivalent GET request.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Path Parameters
Query Parameters
Response
200 -
304 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Create or modify a design document
PUT /{db}/_design/{ddoc}
The PUT method creates a new named design document, or creates a new revision of the existing design document.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.design-document.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.design-document.write
Request
Request Body
Path Parameters
Query Parameters
batch
string
Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.
new_edits
boolean
Query parameter to specify whether to prevent insertion of conflicting document revisions. If false, a well-formed _rev must be included in the document. False is used by the replicator to insert documents into the target database even if that leads to the creation of conflicts.
Avoid using this parameter, since this option applies document revisions without checking for conflicts, so it is very easy to accidentally end up with a large number of conflicts.
rev
Query parameter to specify a document revision.
Response
201 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
409 -
410 -
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
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Query a search index
POST /{db}/_design/{ddoc}/_search/{index}
Search indexes, which are defined in design documents, allow databases to be queried by using Lucene Query Parser Syntax. An index function defines a search index, similar to a map function in MapReduce views. The index function decides what data to index and what data to store in the index. The advantage of using the HTTP `POST` method is that the query is submitted as a JSON object in the request body. This avoids the limitations of passing query options as URL query parameters of a `GET` request.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Retrieve information about a search index
GET /{db}/_design/{ddoc}/_search_info/{index}
Retrieve search index metadata information, such as the size of the index on disk.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Query a MapReduce view
POST /{db}/_design/{ddoc}/_view/{view}
This operation queries the specified MapReduce view of the specified design document. By default, the map and reduce functions of the view are run to update the view before returning the response. The advantage of using the HTTP `POST` method is that the query is submitted as a JSON object in the request body. This avoids the limitations of passing query options as URL query parameters of a `GET` request.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
507 -
Multi-query a MapReduce view
POST /{db}/_design/{ddoc}/_view/{view}/queries
This operation runs multiple specified view queries against the view function from the specified design document.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
507 -
Query a list of all design documents in a database
POST /{db}/_design_docs
Queries the index of all design document IDs. The results matching the request body parameters are returned in a JSON object, including a list of matching design documents with basic contents, such as the ID and revision. When no request body parameters are specified, results for all design documents in the database are returned. Optionally, the design document content or additional metadata can be included in the response.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Multi-query the list of all design documents
POST /{db}/_design_docs/queries
This operation runs multiple view queries of all design documents in the database. This operation enables you to request numerous queries in a single request, in place of multiple POST `/{db}/_design_docs` requests.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Retrieve information about which index is used for a query
POST /{db}/_explain
Shows which index is being used by the query. Parameters are the same as the `_find` endpoint.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
POST /{db}/_find
Query documents by using a declarative JSON querying syntax. It's best practice to create an appropriate index for all fields in selector by using the `_index` endpoint.
Queries without an appropriate backing index by default fallback to using the built-in `_all_docs` index. This isn't recommended because it has a significant performance impact causing a full scan of the database with each request. In this case the response body includes a warning field recommending the creation of an index.
To avoid the fallback behavior set the `allow_fallback` option to `false` and the server responds with a `400` status code if no suitable index exists. If you want to use only a specific index for your query set `allow_fallback` to `false` and set the `use_index` option.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
507 -
Retrieve information about all indexes
GET /{db}/_index
When you make a GET request to `/db/_index`, you get a list of all the indexes using `"language":"query"` in the database and the primary index. In addition to the information available through this API, the indexes are stored in the `indexes` property of their respective design documents.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Create a new index on a database
POST /{db}/_index
Create a new index on a database.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.design-document.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.design-document.write
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Delete an index
DELETE /{db}/_index/_design/{ddoc}/{type}/{index}
Delete the index functions from the design document and index files on the server.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.design-document.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.design-document.write
Request
Path Parameters
db
Required *
Path parameter to specify the database name.
ddoc
Required *
Path parameter to specify the design document name. The design document name is the design document ID excluding the `_design/` prefix.
type
Required *
Path parameter to specify the index type.
index
Required *
string
Path parameter to specify the index name.
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Delete a local document
DELETE /{db}/_local/{doc_id}
Deletes the specified local document. The semantics are identical to deleting a standard document in the specified database, except that the document is not replicated.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.local-document.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.local-document.write
Request
Path Parameters
Query Parameters
batch
string
Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.
Response
200 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve a local document
GET /{db}/_local/{doc_id}
Retrieves the specified local document. The semantics are identical to accessing a standard document in the specified database, except that the document is not replicated.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Path Parameters
Query Parameters
attachments
boolean
Query parameter to specify whether to include attachment content in the response. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
att_encoding_info
boolean
Query parameter to specify whether to include the encoding information for compressed attachments. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
atts_since
array
Query parameter to specify whether to include attachments only since specified revisions. Note this does not include the attachments for the specified revisions.
local_seq
boolean
Query parameter to specify whether to include the last update sequence for the document.
Response
200 -
304 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Create or modify a local document
PUT /{db}/_local/{doc_id}
Stores the specified local document. The semantics are identical to storing a standard document in the specified database, except that the document is not replicated.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.local-document.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.local-document.write
Request
Request Body
Path Parameters
Query Parameters
batch
string
Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.
Response
201 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
507 -
Retrieve information about a database partition
GET /{db}/_partition/{partition_key}
Given a partition key, return the database name, sizes, partition, doc count, and doc delete count.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Query a list of all documents in a database partition
POST /{db}/_partition/{partition_key}/_all_docs
Queries the primary index (all document IDs). The results that match the query parameters are returned in a JSON object, including a list of matching documents with basic contents, such as the ID and revision. When no query parameters are specified, results for all documents in the database partition are returned. Optionally, document content or additional metadata can be included in the response.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Query a database partition search index
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
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Query a database partition MapReduce view function
POST /{db}/_partition/{partition_key}/_design/{ddoc}/_view/{view}
Runs the specified view function from the specified design document. Unlike `GET /{db}/_design/{ddoc}/_view/{view}` for accessing views, the POST method supports the specification of explicit keys to be retrieved from the view results. The remainder of the POST view functionality is identical to the `GET /{db}/_design/{ddoc}/_view/{view}` API.
Before using read the FAQs to understand the limitations and appropriate use cases.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
507 -
Retrieve information about which partition index is used for a query
POST /{db}/_partition/{partition_key}/_explain
Shows which index is being used by the query. Parameters are the same as the `/{db}/_partition/{partition_key}/_find` endpoint.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
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
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
507 -
Query the document revisions and possible ancestors missing from the database
POST /{db}/_revs_diff
The replicator is the primary user of this operation. After receiving a set of new revision IDs from the source database, the replicator sends this set to the destination database's `_revs_diff` to find out which of them already exists there. It can then avoid fetching and sending already-known document bodies.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Request Body
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
413 -
415 -
429 -
500 -
502 -
503 -
504 -
Retrieve shard information
GET /{db}/_shards
List each shard range and the corresponding replicas for a specified database.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.database-shards.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.database-shards.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve shard information for a specific document
GET /{db}/_shards/{doc_id}
Retrieves information about a specific shard where a particular document is stored, along with information about the nodes where that shard has a replica.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.database-shards.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.database-shards.read
Request
Path Parameters
Query Parameters
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Delete a document
DELETE /{db}/{doc_id}
Marks the specified document as deleted by adding a `_deleted` field with the value `true`. Documents with this field are not returned within requests anymore but stay in the database. You must supply the current (latest) revision, either by using the `rev` parameter or by using the `If-Match` header to specify the revision.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.data-document.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.data-document.write
Request
Path Parameters
Query Parameters
batch
string
Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.
rev
Query parameter to specify a document revision.
Response
200 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
409 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve a document
GET /{db}/{doc_id}
Returns document with the specified `doc_id` from the specified database. Unless you request a specific revision, the latest revision of the document is always returned.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Path Parameters
Query Parameters
attachments
boolean
Query parameter to specify whether to include attachment content in the response. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
att_encoding_info
boolean
Query parameter to specify whether to include the encoding information for compressed attachments. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
atts_since
array
Query parameter to specify whether to include attachments only since specified revisions. Note this does not include the attachments for the specified revisions.
conflicts
boolean
Query parameter to specify whether to include a list of conflicted revisions in each returned document. Note that when used with a view-style query or changes feed this only applies when requesting documents in the response.
deleted_conflicts
boolean
Query parameter to specify whether to include a list of deleted conflicted revisions in the `_deleted_conflicts` property of the returned document.
latest
boolean
Query parameter to specify whether to force retrieving latest leaf revision, no matter what rev was requested.
local_seq
boolean
Query parameter to specify whether to include the last update sequence for the document.
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.
open_revs
array
Query parameter to specify leaf revisions to retrieve. Additionally, it accepts a value of `all` to return all leaf revisions.
rev
Query parameter to specify a document revision.
revs
boolean
Query parameter to specify whether to include a list of all known document revisions.
revs_info
boolean
Query parameter to specify whether to includes detailed information for all known document revisions.
Response
200 -
304 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve the HTTP headers for the document
HEAD /{db}/{doc_id}
This method supports the same query arguments as the `GET /{db}/{docid}` method, but only the header information (including document size and the revision as an ETag) is returned. The ETag header shows the current revision for the requested document, and the Content-Length specifies the length of the data if the document was requested in full. Add any of the query arguments, then the resulting HTTP headers that correspond to it are returned.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Path Parameters
Query Parameters
latest
boolean
Query parameter to specify whether to force retrieving latest leaf revision, no matter what rev was requested.
rev
Query parameter to specify a document revision.
Response
200 -
304 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
429 -
500 -
502 -
503 -
504 -
PUT /{db}/{doc_id}
Creates or modifies a document in the specified database.
For creation, you must specify the document ID but you should not specify the revision.
For modification, you must specify the document ID and a revision identifier.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.data-document.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.data-document.write
Request
Request Body
Path Parameters
Query Parameters
batch
string
Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.
new_edits
boolean
Query parameter to specify whether to prevent insertion of conflicting document revisions. If false, a well-formed _rev must be included in the document. False is used by the replicator to insert documents into the target database even if that leads to the creation of conflicts.
Avoid using this parameter, since this option applies document revisions without checking for conflicts, so it is very easy to accidentally end up with a large number of conflicts.
rev
Query parameter to specify a document revision.
Response
201 -
202 -
400 -
401 -
402 -
403 -
404 -
408 -
409 -
410 -
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
Path Parameters
Query Parameters
rev
Query parameter to specify a document revision.
batch
string
Query parameter to specify whether to store in batch mode. The server will respond with a HTTP 202 Accepted response code immediately.
Response
200 -
400 -
401 -
402 -
403 -
404 -
408 -
409 -
410 -
429 -
500 -
502 -
503 -
504 -
Retrieve an attachment
GET /{db}/{doc_id}/{attachment_name}
Returns the file attachment that is associated with the document. The raw data of the associated attachment is returned, just as if you were accessing a static file. The returned Content-Type header is the same as the content type set when the document attachment was submitted to the database.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Path Parameters
Query Parameters
rev
Query parameter to specify a document revision.
Response
200 -
206 -
304 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
416 -
429 -
500 -
502 -
503 -
504 -
Retrieve the HTTP headers for an attachment
HEAD /{db}/{doc_id}/{attachment_name}
Returns the HTTP headers that contain a minimal amount of information about the specified attachment. This method supports the same query arguments as the `GET /{db}/{doc_id}/{attachment_name}` method, but only the header information (including attachment size, encoding, and the MD5 hash as an ETag), is returned.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.any-document.read
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.any-document.read
Request
Path Parameters
Query Parameters
rev
Query parameter to specify a document revision.
Response
200 -
206 -
304 -
400 -
401 -
402 -
403 -
404 -
408 -
410 -
416 -
429 -
500 -
502 -
503 -
504 -
Create or modify an attachment
PUT /{db}/{doc_id}/{attachment_name}
Uploads the supplied content as an attachment to the specified document. The attachment name that you provide must be a URL encoded string. You must supply the Content-Type header, and for an existing document, you must also supply either the `rev` query argument or the `If-Match` HTTP header. If you omit the revision, a new, otherwise empty, document is created with the provided attachment, or a conflict occurs. If the uploaded attachment uses an existing attachment name in the remote database, it updates the corresponding stored content of the database. Since you must supply the revision information to add an attachment to the document, this serves as validation to update the existing attachment.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloudantnosqldb.data-document.write
Auditing
Calling this method generates the following auditing event.
cloudantnosqldb.data-document.write
Request
Request Body
Path Parameters
Query Parameters
rev
Query parameter to specify a document revision.