### Navigation

- index
- next |
- previous |
- Apache CouchDB 1.3 Manual »
- 18. API Reference »

# 18.4. Document Methods

The CouchDB API Server Document methods detail how to create, read, update and delete documents within a database.

A list of the available methods and URL paths are provided below:

Method | Path | Description
--- | --- | ---
POST | /db | Create a new document
GET | /db/doc | Returns the latest revision of the document
HEAD | /db/doc | Returns bare information in the HTTP Headers for the document
PUT | /db/doc | Inserts a new document, or new version of an existing document
DELETE | /db/doc | Deletes the document
COPY | /db/doc | Copies the document
GET | /db/doc/attachment | Gets the attachment of a document
PUT | /db/doc/attachment | Adds an attachment of a document
DELETE | /db/doc/attachment | Deletes an attachment of a document

## 18.4.1. `POST /db`

- Method: `POST /db`
- Request: JSON of the new document
- Response: JSON with the committed document information
- Admin Privileges Required: no
- Query Arguments:
  - Argument: batch
    - Description: Allow document store request to be batched with others
    - Optional: yes
    - Type: string
    - Supported Values: asd
    - ok: Enable
- Return Codes:
  - 201: Document has been created successfully
  - 409: Conflict - a document with the specified document ID already exists

Create a new document in the specified database, using the supplied JSON document structure. If the JSON structure includes the `_id` field, then the document will be created with the specified document ID. If the `_id` field is not specified, a new unique ID will be generated.

For example, you can generate a new document with a generated UUID using the following request:

    POST http://couchdb:5984/recipes/
    Content-Type: application/json

    {
       "servings" : 4,
       "subtitle" : "Delicious with fresh bread",
       "title" : "Fish Stew"
    }

The return JSON will specify the automatically generated ID and revision information:

    {
       "id" : "64575eef70ab90a2b8d55fc09e00440d",
       "ok" : true,
       "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
    }

### 18.4.1.1. Specifying the Document ID

The document ID can be specified by including the `_id` field in the JSON of the submitted record. The following request will create the same document with the ID `FishStew`:

    POST http://couchdb:5984/recipes/
    Content-Type: application/json

    {
       "_id" : "FishStew",
       "servings" : 4,
       "subtitle" : "Delicious with fresh bread",
       "title" : "Fish Stew"
    }

The structure of the submitted document is as shown in the table below:

In either case, the returned JSON will specify the document ID, revision ID, and status message:

    {
       "id" : "FishStew",
       "ok" : true,
       "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
    }

### 18.4.1.2. UUID generation algorithms

CouchDB supports a number of different UUID generation algorithms for use in situations where a user-specified UUID does not make sense. These can be set simply by PUT http://couchdb:5984/_config/uuids/algorithm.

Algorithm | Description | Sample UUID
--- | --- | ---
random | 128 bits of pure random awesomeness | 43febce5675468a5467fb5467ce9e6c0
sequential | monotonically increasing ids with random increments | f755c413badf66b22941313f9f001e28 f755c413badf66b22941313f9f0024ca f755c413badf66b22941313f9f00332c
utc_random | time since start of epoch, as 14 hex digits, followed by 18 random digits. | 04cfa405381205204f75100d0241ccc3 04cfa4059c48e76e7c054bbe033dd8db 04cfa405fce10b0df4c08f95e667cd2f
utc_id & additional parameter | time since start of epoch, as 14 hex digits, followed by utc_id_suffix. | 04cfa718b00848_i_am_in_yer_couch 04cfa71d377aef_i_am_in_yer_couch 04cfa71e0deabd_i_am_in_yer_couch

### 18.4.1.3. Batch Mode Writes

You can write documents to the database at a higher rate by using the batch option. This collects document writes together in memory (on a user-by-user basis) before they are committed to disk. This increases the risk of the documents not being stored in the event of a failure, since the documents are not written to disk immediately.

To use the batched mode, append the `batch=ok` query argument to the URL of the `PUT` or `POST` request. The CouchDB server will respond with a 202 HTTP response code immediately.

### 18.4.1.4. Including Attachments

You can include one or more attachments with a given document by incorporating the attachment information within the JSON of the document. This provides a simpler alternative to loading documents with attachments than making a separate call (see PUT /db/doc/attachment).

- _id (optional): Document ID
- _rev (optional): Revision ID (when updating an existing document)
- _attachments (optional): Document Attachment
  - filename: Attachment information
    - content_type: MIME Content type string
    - data: File attachment content, Base64 encoded

The `filename` will be the attachment name. For example, when sending the JSON structure below:

    {
       "_id" : "FishStew",
       "servings" : 4,
       "subtitle" : "Delicious with fresh bread",
       "title" : "Fish Stew"
       "_attachments" : {
          "styling.css" : {
             "content-type" : "text/css",
             "data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=",
             },
       },
    }

The attachment `styling.css` can be accessed using `/recipes/FishStew/styling.css`. For more information on attachments, see GET /db/doc/attachment.

The document data embedded in to the structure must be encoded using base64.

## 18.4.2. `GET /db/doc`

- Method: `GET /db/doc`
- Request: None
- Response: Returns the JSON for the document
- Admin Privileges Required: no
- Query Arguments:
  - Argument: conflicts
    - Description: Returns the conflict tree for the document.
    - Optional: yes
    - Type: boolean
    - Default: false
    - Supported Values:
      - true: Includes the revisions
  - Argument: rev
    - Description: Specify the revision to return
    - Optional: yes
    - Type: string
    - Supported Values:
      - true: Includes the revisions
  - Argument: revs
    - Description: Return a list of the revisions for the document
    - Optional: yes
    - Type: boolean
  - Argument: revs_info
    - Description: Return a list of detailed revision information for the document
    - Optional: yes
    - Type: boolean
    - Supported Values:
      - true: Includes the revisions
- Return Codes:
  - 200: Document retrieved
  - 400: The format of the request or revision was invalid
  - 404: The specified document or revision cannot be found, or has been deleted
  - 409: Conflict - a document with the specified document ID already exists

Returns the specified `doc` from the specified `db`. For example, to retrieve the document with the id `FishStew` you would send the following request:

    GET http://couchdb:5984/recipes/FishStew
    Content-Type: application/json
    Accept: application/json

The returned JSON is the JSON of the document, including the document ID and revision number:

    {
       "_id" : "FishStew",
       "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c",
       "servings" : 4,
       "subtitle" : "Delicious with a green salad",
       "title" : "Irish Fish Stew"
    }

Unless you request a specific revision, the latest revision of the document will always be returned.

### 18.4.2.1. Attachments

If the document includes attachments, then the returned structure will contain a summary of the attachments associated with the document, but not the attachment data itself.

The JSON for the returned document will include the `_attachments` field, with one or more attachment definitions. For example:

    {
       "_id" : "FishStew",
       "servings" : 4,
       "subtitle" : "Delicious with fresh bread",
       "title" : "Fish Stew"
       "_attachments" : {
          "styling.css" : {
             "stub" : true,
             "content-type" : "text/css",
             "length" : 783426,
             },
       },
    }

The format of the returned JSON is shown in the table below:

- _id (optional): Document ID
- _rev (optional): Revision ID (when updating an existing document)
- _attachments (optional): Document Attachment
  - filename: Attachment information
    - content_type: MIME Content type string
    - length: Length (bytes) of the attachment data
    - revpos: Revision where this attachment exists
    - stub: Indicates whether the attachment is a stub

### 18.4.2.2. Getting a List of Revisions

You can obtain a list of the revisions for a given document by adding the `revs=true` parameter to the request URL. For example:

    GET http://couchdb:5984/recipes/FishStew?revs=true
    Accept: application/json

The returned JSON structure includes the original document, including a `_revisions` structure that includes the revision information:

    {
       "servings" : 4,
       "subtitle" : "Delicious with a green salad",
       "_id" : "FishStew",
       "title" : "Irish Fish Stew",
       "_revisions" : {
          "ids" : [
             "a1a9b39ee3cc39181b796a69cb48521c",
             "7c4740b4dcf26683e941d6641c00c39d",
             "9c65296036141e575d32ba9c034dd3ee"
          ],
          "start" : 3
       },
       "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
    }

- _id (optional): Document ID
- _rev (optional): Revision ID (when updating an existing document)
- _revisions: CouchDB Document Revisions
  - ids [array]: Array of valid revision IDs, in reverse order (latest first)
  - start: Prefix number for the latest revision

### 18.4.2.3. Obtaining an Extended Revision History

You can get additional information about the revisions for a given document by supplying the `revs_info` argument to the query:

    GET http://couchdb:5984/recipes/FishStew?revs_info=true
    Accept: application/json

This returns extended revision information, including the availability and status of each revision:

    {
       "servings" : 4,
       "subtitle" : "Delicious with a green salad",
       "_id" : "FishStew",
       "_revs_info" : [
          {
             "status" : "available",
             "rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
          },
          {
             "status" : "available",
             "rev" : "2-7c4740b4dcf26683e941d6641c00c39d"
          },
          {
             "status" : "available",
             "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
          }
       ],
       "title" : "Irish Fish Stew",
       "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
    }

- _id (optional): Document ID
- _rev (optional): Revision ID (when updating an existing document)
- _revs_info [array]: CouchDB Document Extended Revision Info
  - rev: Full revision string
  - status: Status of the revision

### 18.4.2.4. Obtaining a Specific Revision

To get a specific revision, use the `rev` argument to the request, and specify the full revision number:

    GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d
    Accept: application/json

The specified revision of the document will be returned, including a `_rev` field specifying the revision that was requested:

    {
       "_id" : "FishStew",
       "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d",
       "servings" : 4,
       "subtitle" : "Delicious with a green salad",
       "title" : "Fish Stew"
    }

## 18.4.3. `HEAD /db/doc`

- Method: `HEAD /db/doc`
- Request: None
- Response: None
- Admin Privileges Required: no
- Query Arguments:
  - Argument: rev
    - Description: Specify the revision to return
    - Optional: yes
    - Type: string
  - Argument: revs
    - Description: Return a list of the revisions for the document
    - Optional: yes
    - Type: boolean
  - Argument: revs_info
    - Description: Return a list of detailed revision information for the document
    - Optional: yes
    - Type: boolean
- Return Codes:
  - 404: The specified document or revision cannot be found, or has been deleted

Returns the HTTP Headers containing a minimal amount of information about the specified document. The method supports the same query arguments as the `GET` method, but only the header information (including document size, and the revision as an ETag), is returned. For example, a simple `HEAD` request:

    HEAD http://couchdb:5984/recipes/FishStew
    Content-Type: application/json

Returns the following HTTP Headers:

    HTTP/1.1 200 OK
    Server: CouchDB/1.0.1 (Erlang OTP/R13B)
    Etag: "7-a19a1a5ecd946dad70e85233ba039ab2"
    Date: Fri, 05 Nov 2010 14:54:43 GMT
    Content-Type: text/plain;charset=utf-8
    Content-Length: 136
    Cache-Control: must-revalidate

The `Etag` header shows the current revision for the requested document, and the `Content-Length` specifies the length of the data, if the document were requested in full.

Adding any of the query arguments (as supported by ``GET```_ method), then the resulting HTTP Headers will correspond to what would be returned. Note that the current revision is not returned when the ``refs_info` argument is used. For example:

    HTTP/1.1 200 OK
    Server: CouchDB/1.0.1 (Erlang OTP/R13B)
    Date: Fri, 05 Nov 2010 14:57:16 GMT
    Content-Type: text/plain;charset=utf-8
    Content-Length: 609
    Cache-Control: must-revalidate

## 18.4.4. `PUT /db/doc`

- Method: `PUT /db/doc`
- Request: JSON of the new document, or updated version of the existed document
- Response: JSON of the document ID and revision
- Admin Privileges Required: no
- Query Arguments:
  - Argument: batch
    - Description: Allow document store request to be batched with others
    - Optional: yes
    - Type: string
    - Supported Values:
      - ok: Enable
- HTTP Headers
  - Header: `If-Match`
    - Description: Current revision of the document for validation
    - Optional: yes
- Return Codes:
  - 201: Document has been created successfully
  - 202: Document accepted for writing (batch mode)

The `PUT` method creates a new named document, or creates a new revision of the existing document. Unlike the `POST` method, you must specify the document ID in the request URL.

For example, to create the document `FishStew`, you would send the following request:

    PUT http://couchdb:5984/recipes/FishStew
    Content-Type: application/json

    {
      "servings" : 4,
      "subtitle" : "Delicious with fresh bread",
      "title" : "Fish Stew"
    }

The return type is JSON of the status, document ID,and revision number:

    {
       "id" : "FishStew",
       "ok" : true,
       "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
    }

### 18.4.4.1. Updating an Existing Document

To update an existing document you must specify the current revision number within the `_rev` parameter. For example:

    PUT http://couchdb:5984/recipes/FishStew
    Content-Type: application/json

    {
      "_rev" : "1-9c65296036141e575d32ba9c034dd3ee",
      "servings" : 4,
      "subtitle" : "Delicious with fresh salad",
      "title" : "Fish Stew"
    }

Alternatively, you can supply the current revision number in the `If-Match` HTTP header of the request. For example:

    PUT http://couchdb:5984/recipes/FishStew
    If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea
    Content-Type: application/json

    {
       "servings" : 4,
       "subtitle" : "Delicious with fresh salad",
       "title" : "Fish Stew"
    }

The JSON returned will include the updated revision number:

    {
       "id" : "FishStew99",
       "ok" : true,
       "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea"
    }

For information on batched writes, which can provide improved performance, see UUID generation algorithms.

## 18.4.5. `DELETE /db/doc`

- Method: `DELETE /db/doc`
- Request: None
- Response: JSON of the deleted revision
- Admin Privileges Required: no
- Query Arguments:
  - Argument: rev
    - Description: Current revision of the document for validation
    - Optional: yes
    - Type: string
- HTTP Headers
  - Header: `If-Match`
    - Description: Current revision of the document for validation
    - Optional: yes
- Return Codes:
  - 409: Revision is missing, invalid or not the latest

Deletes the specified document from the database. You must supply the current (latest) revision, either by using the `rev` parameter to specify the revision:

    DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c
    Content-Type: application/json

Alternatively, you can use ETags with the `If-Match` field:

    DELETE http://couchdb:5984/recipes/FishStew
    If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c
    Content-Type: application/json

The returned JSON contains the document ID, revision and status:

    {
       "id" : "FishStew",
       "ok" : true,
       "rev" : "4-2719fd41187c60762ff584761b714cfb"
    }

Note

Note that deletion of a record increments the revision number. The use of a revision for deletion of the record allows replication of the database to correctly track the deletion in synchronized copies.

## 18.4.6. `COPY /db/doc`

- Method: `COPY /db/doc`
- Request: None
- Response: JSON of the new document and revision
- Admin Privileges Required: no
- Query Arguments:
  - Argument: rev
    - Description: Revision to copy from
    - Optional: yes
    - Type: string
- HTTP Headers
  - Header: `Destination`
    - Description: Destination document (and optional revision)
    - Optional: no
- Return Codes:
  - 201: Document has been copied and created successfully
  - 409: Revision is missing, invalid or not the latest

The `COPY` command (which is non-standard HTTP) copies an existing document to a new or existing document.

The source document is specified on the request line, with the `Destination` HTTP Header of the request specifying the target document.

### 18.4.6.1. Copying a Document

You can copy the latest version of a document to a new document by specifying the current document and target document:

    COPY http://couchdb:5984/recipes/FishStew
    Content-Type: application/json
    Destination: IrishFishStew

The above request copies the document `FishStew` to the new document `IrishFishStew`. The response is the ID and revision of the new document.

    {
       "id" : "IrishFishStew",
       "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
    }

### 18.4.6.2. Copying from a Specific Revision

To copy from a specific version, use the `rev` argument to the query string:

    COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082
    Content-Type: application/json
    Destination: IrishFishStew

The new document will be created using the information in the specified revision of the source document.

### 18.4.6.3. Copying to an Existing Document

To copy to an existing document, you must specify the current revision string for the target document, using the `rev` parameter to the `Destination` HTTP Header string. For example:

    COPY http://couchdb:5984/recipes/FishStew
    Content-Type: application/json
    Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee

The return value will be the new revision of the copied document:

    {
       "id" : "IrishFishStew",
       "rev" : "2-55b6a1b251902a2c249b667dab1c6692"
    }

## 18.4.7. `GET /db/doc/attachment`

- Method: `GET /db/doc/attachment`
- Request: None
- Response: Returns the attachment data
- Admin Privileges Required: no

Returns the file attachment `attachment` associated with the document `doc`. The raw data of the associated attachment is returned (just as if you were accessing a static file. The returned HTTP `Content-type` will be the same as the content type set when the document attachment was submitted into the database.

## 18.4.8. `PUT /db/doc/attachment`

- Method: `PUT /db/doc/attachment`
- Request: Raw document data
- Response: JSON document status
- Admin Privileges Required: no
- Query Arguments:
  - Argument: rev
    - Description: Current document revision
    - Optional: no
    - Type: string
- HTTP Headers
  - Header: `Content-Length`
    - Description: Length (bytes) of the attachment being uploaded
    - Optional: no
  - Header: `Content-Type`
    - Description: MIME type for the uploaded attachment
    - Optional: no
  - Header: `If-Match`
    - Description: Current revision of the document for validation
    - Optional: yes
- Return Codes:
  - 201: Attachment has been accepted

Upload the supplied content as an attachment to the specified document (`doc`). The `attachment` name provided must be a URL encoded string. You must also supply either the `rev` query argument or the `If-Match` HTTP header for validation, and the HTTP headers (to set the attachment content type). The content type is used when the attachment is requested as the corresponding content-type in the returned document header.

For example, you could upload a simple text document using the following request:

    PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca
    Content-Length: 10
    Content-Type: text/plain

    Roast it

Or by using the `If-Match` HTTP header:

    PUT http://couchdb:5984/recipes/FishStew/basic
    If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca
    Content-Length: 10
    Content-Type: text/plain

    Roast it

The returned JSON contains the new document information:

    {
       "id" : "FishStew",
       "ok" : true,
       "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74"
    }

Note

Uploading an attachment updates the corresponding document revision. Revisions are tracked for the parent document, not individual attachments.

### 18.4.8.1. Updating an Existing Attachment

Uploading an attachment using an existing attachment name will update the corresponding stored content of the database. Since you must supply the revision information to add an attachment to a document, this serves as validation to update the existing attachment.

## 18.4.9. `DELETE /db/doc/attachment`

- Method: `DELETE /db/doc/attachment`
- Request: None
- Response: JSON status
- Admin Privileges Required: no
- Query Arguments:
  - Argument: rev
    - Description: Current document revision
    - Optional: no
    - Type: string
- HTTP Headers
  - Header: `If-Match`
    - Description: Current revision of the document for validation
    - Optional: yes
- Return Codes:
  - 200: Attachment deleted successfully
  - 409: Supplied revision is incorrect or missing

Deletes the attachment `attachment` to the specified `doc`. You must supply the `rev` argument with the current revision to delete the attachment.

For example to delete the attachment `basic` from the recipe `FishStew`:

    DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74
    Content-Type: application/json

The returned JSON contains the updated revision information:

    {
       "id" : "FishStew",
       "ok" : true,
       "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e"
    }

### Navigation

- index
- next |
- previous |
- Apache CouchDB 1.3 Manual »
- 18. API Reference »