# 1.4.1. `/{db}/{docid}`

HEAD /{db}/{docid}

  Returns the HTTP Headers containing a minimal amount of information about the specified document. The 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 were requested in full.

  Adding any of the query arguments (see `GET /{db}/{docid}`), then the resulting HTTP Headers will correspond to what would be returned.

  Parameters:

    - db – Database name

    - docid – Document ID

  Request Headers:

    - If-None-Match – Double quoted document’s revision token

  Response Headers:

    - Content-Length – Document size

    - ETag – Double quoted document’s revision token

  Status Codes:

    - 200 OK – Document exists

    - 304 Not Modified – Document wasn’t modified since specified revision

    - 401 Unauthorized – Read privilege required

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

    - 404 Not Found – Document not found

  Request:

      HEAD /db/SpaghettiWithMeatballs HTTP/1.1
      Accept: application/json
      Host: localhost:5984

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 660
      Content-Type: application/json
      Date: Tue, 13 Aug 2013 21:35:37 GMT
      ETag: "12-151bb8678d45aaa949ec3698ef1c7e78"
      Server: CouchDB (Erlang/OTP)

GET /{db}/{docid}

  Returns document by the specified `docid` from the specified `db`. Unless you request a specific revision, the latest revision of the document will always be returned.

  Parameters:

    - db – Database name

    - docid – Document ID

  Request Headers:

    - Accept –

      - application/json

      - multipart/related

      - multipart/mixed

      - text/plain

    - If-None-Match – Double quoted document’s revision token

  Query Parameters:

    - attachments (boolean) – Includes attachments bodies in response. Default is `false`

    - att_encoding_info (boolean) – Includes encoding information in attachment stubs if the particular attachment is compressed. Default is `false`.

    - atts_since (array) – Includes attachments only since specified revisions. Doesn’t includes attachments for specified revisions. Optional

    - conflicts (boolean) – Includes information about conflicts in document. Default is `false`

    - deleted_conflicts (boolean) – Includes information about deleted conflicted revisions. Default is `false`

    - latest (boolean) – Forces retrieving latest “leaf” revision, no matter what rev was requested. Default is `false`

    - local_seq (boolean) – Includes last update sequence for the document. Default is `false`

    - meta (boolean) – Acts same as specifying all `conflicts`, `deleted_conflicts` and `revs_info` query parameters. Default is `false`

    - open_revs (array) – Retrieves documents of specified leaf revisions. Additionally, it accepts value as `all` to return all leaf revisions. Optional

    - rev (string) – Retrieves document of specified revision. Optional

    - revs (boolean) – Includes list of all known document revisions. Default is `false`

    - revs_info (boolean) – Includes detailed information for all known document revisions. Default is `false`

  Response Headers:

    - Content-Type –

      - application/json

      - multipart/related

      - multipart/mixed

      - text/plain; charset=utf-8

    - ETag – Double quoted document’s revision token. Not available when retrieving conflicts-related information

    - Transfer-Encoding – `chunked`. Available if requested with query parameter `open_revs`

  Response JSON Object:

    - _id (string) – Document ID

    - _rev (string) – Revision MVCC token

    - _deleted (boolean) – Deletion flag. Available if document was removed

    - _attachments (object) – Attachment’s stubs. Available if document has any attachments

    - _conflicts (array) – List of conflicted revisions. Available if requested with `conflicts=true` query parameter

    - _deleted_conflicts (array) – List of deleted conflicted revisions. Available if requested with `deleted_conflicts=true` query parameter

    - _local_seq (string) – Document’s update sequence in current database. Available if requested with `local_seq=true` query parameter

    - _revs_info (array) – List of objects with information about local revisions and their status. Available if requested with `open_revs` query parameter

    - _revisions (object) – List of local revision tokens without. Available if requested with `revs=true` query parameter

  Status Codes:

    - 200 OK – Request completed successfully

    - 304 Not Modified – Document wasn’t modified since specified revision

    - 400 Bad Request – The format of the request or revision was invalid

    - 401 Unauthorized – Read privilege required

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

    - 404 Not Found – Document not found

  Request:

      GET /recipes/SpaghettiWithMeatballs HTTP/1.1
      Accept: application/json
      Host: localhost:5984

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 660
      Content-Type: application/json
      Date: Tue, 13 Aug 2013 21:35:37 GMT
      ETag: "1-917fa2381192822767f010b95b45325b"
      Server: CouchDB (Erlang/OTP)

      {
          "_id": "SpaghettiWithMeatballs",
          "_rev": "1-917fa2381192822767f010b95b45325b",
          "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
          "ingredients": [
              "spaghetti",
              "tomato sauce",
              "meatballs"
          ],
          "name": "Spaghetti with meatballs"
      }

PUT /{db}/{docid}

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

  When updating an existing document, the current document revision must be included in the document (i.e. the request body), as the `rev` query parameter, or in the `If-Match` request header.

  Parameters:

    - db – Database name

    - docid – Document ID

  Request Headers:

    - Accept –

      - application/json

      - text/plain

    - Content-Type –

      - application/json

      - multipart/related

    - If-Match – Document’s revision. Alternative to rev query parameter or document key. Optional

  Query Parameters:

    - rev (string) – Document’s revision if updating an existing document. Alternative to `If-Match` header or document key. Optional

    - batch (string) – Stores document in batch mode. Possible values: `ok`. Optional

    - new_edits (boolean) – Prevents insertion of a conflicting document. Possible values: `true` (default) and `false`. If `false`, a well-formed `_rev` must be included in the document. `new_edits=false` is used by the replicator to insert documents into the target database even if that leads to the creation of conflicts. Optional, The ``false`` value is intended for use only by the replicator.

  Response Headers:

    - Content-Type –

      - application/json

      - text/plain; charset=utf-8

      - multipart/related

    - ETag – Quoted document’s new revision

    - Location – Document URI

  Response JSON Object:

    - id (string) – Document ID

    - ok (boolean) – Operation status

    - rev (string) – Revision MVCC token

  Status Codes:

    - 201 Created – Document created and stored on disk

    - 202 Accepted – Document data accepted, but not yet stored on disk

    - 400 Bad Request – Invalid request body or parameters

    - 401 Unauthorized – Write privileges required

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

    - 404 Not Found – Specified database or document ID doesn’t exists

    - 409 Conflict – Document with the specified ID already exists or specified revision is not latest for target document

  Request:

      PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
      Accept: application/json
      Content-Length: 196
      Content-Type: application/json
      Host: localhost:5984

      {
          "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
          "ingredients": [
              "spaghetti",
              "tomato sauce",
              "meatballs"
          ],
          "name": "Spaghetti with meatballs"
      }

  Response:

      HTTP/1.1 201 Created
      Cache-Control: must-revalidate
      Content-Length: 85
      Content-Type: application/json
      Date: Wed, 14 Aug 2013 20:31:39 GMT
      ETag: "1-917fa2381192822767f010b95b45325b"
      Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
      Server: CouchDB (Erlang/OTP)

      {
          "id": "SpaghettiWithMeatballs",
          "ok": true,
          "rev": "1-917fa2381192822767f010b95b45325b"
      }

DELETE /{db}/{docid}

  Marks the specified document as deleted by adding a field `_deleted` with the value `true`. Documents with this field will not be 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.

  Note

  CouchDB doesn’t completely delete the specified document. Instead, it leaves a tombstone with very basic information about the document. The tombstone is required so that the delete action can be replicated across databases.

  See also

  Retrieving Deleted Documents

  Parameters:

    - db – Database name

    - docid – Document ID

  Request Headers:

    - Accept –

      - application/json

      - text/plain

    - If-Match – Document’s revision. Alternative to rev query parameter

  Query Parameters:

    - rev (string) – Actual document’s revision

    - batch (string) – Stores document in batch mode Possible values: `ok`. Optional

  Response Headers:

    - Content-Type –

      - application/json

      - text/plain; charset=utf-8

    - ETag – Double quoted document’s new revision

  Response JSON Object:

    - id (string) – Document ID

    - ok (boolean) – Operation status

    - rev (string) – Revision MVCC token

  Status Codes:

    - 200 OK – Document successfully removed

    - 202 Accepted – Request was accepted, but changes are not yet stored on disk

    - 400 Bad Request – Invalid request body or parameters

    - 401 Unauthorized – Write privileges required

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

    - 404 Not Found – Specified database or document ID doesn’t exists

    - 409 Conflict – Specified revision is not the latest for target document

  Request:

      DELETE /recipes/FishStew?rev=1-9c65296036141e575d32ba9c034dd3ee HTTP/1.1
      Accept: application/json
      Host: localhost:5984

  Alternatively, instead of `rev` query parameter you may use If-Match header:

      DELETE /recipes/FishStew HTTP/1.1
      Accept: application/json
      If-Match: 1-9c65296036141e575d32ba9c034dd3ee
      Host: localhost:5984

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 71
      Content-Type: application/json
      Date: Wed, 14 Aug 2013 12:23:13 GMT
      ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
      Server: CouchDB (Erlang/OTP)

      {
          "id": "FishStew",
          "ok": true,
          "rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
      }

COPY /{db}/{docid}

  The COPY (which is non-standard HTTP) copies an existing document to a new or existing document. Copying a document is only possible within the same database.

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

  Parameters:

    - db – Database name

    - docid – Document ID

  Request Headers:

    - Accept –

      - application/json

      - text/plain

    - Destination – Destination document. Must contain the target document ID, and optionally the target document revision, if copying to an existing document. See Copying to an Existing Document.

    - If-Match – Source document’s revision. Alternative to `rev` query parameter

  Query Parameters:

    - rev (string) – Revision to copy from. Optional

    - batch (string) – Stores document in batch mode Possible values: `ok`. Optional

  Response Headers:

    - Content-Type –

      - application/json

      - text/plain; charset=utf-8

    - ETag – Double quoted document’s new revision

    - Location – Document URI

  Response JSON Object:

    - id (string) – Document document ID

    - ok (boolean) – Operation status

    - rev (string) – Revision MVCC token

  Status Codes:

    - 201 Created – Document successfully created

    - 202 Accepted – Request was accepted, but changes are not yet stored on disk

    - 400 Bad Request – Invalid request body or parameters

    - 401 Unauthorized – Read or write privileges required

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

    - 404 Not Found – Specified database, document ID or revision doesn’t exists

    - 409 Conflict – Document with the specified ID already exists or specified revision is not latest for target document

  Request:

      COPY /recipes/SpaghettiWithMeatballs HTTP/1.1
      Accept: application/json
      Destination: SpaghettiWithMeatballs_Italian
      Host: localhost:5984

  Response:

      HTTP/1.1 201 Created
      Cache-Control: must-revalidate
      Content-Length: 93
      Content-Type: application/json
      Date: Wed, 14 Aug 2013 14:21:00 GMT
      ETag: "1-e86fdf912560c2321a5fcefc6264e6d9"
      Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Italian
      Server: CouchDB (Erlang/OTP)

      {
          "id": "SpaghettiWithMeatballs_Italian",
          "ok": true,
          "rev": "1-e86fdf912560c2321a5fcefc6264e6d9"
      }

## 1.4.1.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.

The `_attachments` object keys are attachments names while values are information objects with next structure:

- content_type (string): Attachment MIME type

- data (string): Base64-encoded content. Available if attachment content is requested by using the following query parameters:

  > - `attachments=true` when querying a document

  > - `attachments=true&include_docs=true` when querying a changes feed or a view

  > - `atts_since`.

- digest (string): Content hash digest. It starts with prefix which announce hash type (`md5-`) and continues with Base64-encoded hash digest

- encoded_length (number): Compressed attachment size in bytes. Available if `content_type` is in `list of compressible types` when the attachment was added and the following query parameters are specified:

  > - `att_encoding_info=true` when querying a document

  > - `att_encoding_info=true&include_docs=true` when querying a changes feed or a view

- encoding (string): Compression codec. Available if `content_type` is in `list of compressible types` when the attachment was added and the following query parameters are specified:

  > - `att_encoding_info=true` when querying a document

  > - `att_encoding_info=true&include_docs=true` when querying a changes feed or a view

- length (number): Real attachment size in bytes. Not available if attachment content requested

- revpos (number): Revision number when attachment was added

- stub (boolean): Has `true` value if object contains stub info and no content. Otherwise omitted in response

### 1.4.1.1.1. Basic Attachments Info

Request:

    GET /recipes/SpaghettiWithMeatballs HTTP/1.1
    Accept: application/json
    Host: localhost:5984

Response:

    HTTP/1.1 200 OK
    Cache-Control: must-revalidate
    Content-Length: 660
    Content-Type: application/json
    Date: Tue, 13 Aug 2013 21:35:37 GMT
    ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
    Server: CouchDB (Erlang/OTP)

    {
        "_attachments": {
            "grandma_recipe.txt": {
                "content_type": "text/plain",
                "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
                "length": 1872,
                "revpos": 4,
                "stub": true
            },
            "my_recipe.txt": {
                "content_type": "text/plain",
                "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
                "length": 85,
                "revpos": 5,
                "stub": true
            },
            "photo.jpg": {
                "content_type": "image/jpeg",
                "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
                "length": 165504,
                "revpos": 2,
                "stub": true
            }
        },
        "_id": "SpaghettiWithMeatballs",
        "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
        "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
        "ingredients": [
            "spaghetti",
            "tomato sauce",
            "meatballs"
        ],
        "name": "Spaghetti with meatballs"
    }

### 1.4.1.1.2. Retrieving Attachments Content

It’s possible to retrieve document with all attached files content by using `attachments=true` query parameter:

Request:

    GET /db/pixel?attachments=true HTTP/1.1
    Accept: application/json
    Host: localhost:5984

Response:

    HTTP/1.1 200 OK
    Cache-Control: must-revalidate
    Content-Length: 553
    Content-Type: application/json
    Date: Wed, 14 Aug 2013 11:32:40 GMT
    ETag: "4-f1bcae4bf7bbb92310079e632abfe3f4"
    Server: CouchDB (Erlang/OTP)

    {
        "_attachments": {
            "pixel.gif": {
                "content_type": "image/gif",
                "data": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
                "digest": "md5-2JdGiI2i2VELZKnwMers1Q==",
                "revpos": 2
            },
            "pixel.png": {
                "content_type": "image/png",
                "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAAXNSR0IArs4c6QAAAANQTFRFAAAAp3o92gAAAAF0Uk5TAEDm2GYAAAABYktHRACIBR1IAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH3QgOCx8VHgmcNwAAAApJREFUCNdjYAAAAAIAAeIhvDMAAAAASUVORK5CYII=",
                "digest": "md5-Dgf5zxgGuchWrve73evvGQ==",
                "revpos": 3
            }
        },
        "_id": "pixel",
        "_rev": "4-f1bcae4bf7bbb92310079e632abfe3f4"
    }

Or retrieve attached files content since specific revision using `atts_since` query parameter:

Request:

    GET /recipes/SpaghettiWithMeatballs?atts_since=[%224-874985bc28906155ba0e2e0538f67b05%22]  HTTP/1.1
    Accept: application/json
    Host: localhost:5984

Response:

    HTTP/1.1 200 OK
    Cache-Control: must-revalidate
    Content-Length: 760
    Content-Type: application/json
    Date: Tue, 13 Aug 2013 21:35:37 GMT
    ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
    Server: CouchDB (Erlang/OTP)

    {
        "_attachments": {
            "grandma_recipe.txt": {
                "content_type": "text/plain",
                "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
                "length": 1872,
                "revpos": 4,
                "stub": true
            },
            "my_recipe.txt": {
                "content_type": "text/plain",
                "data": "MS4gQ29vayBzcGFnaGV0dGkKMi4gQ29vayBtZWV0YmFsbHMKMy4gTWl4IHRoZW0KNC4gQWRkIHRvbWF0byBzYXVjZQo1LiAuLi4KNi4gUFJPRklUIQ==",
                "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
                "revpos": 5
            },
            "photo.jpg": {
                "content_type": "image/jpeg",
                "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
                "length": 165504,
                "revpos": 2,
                "stub": true
            }
        },
        "_id": "SpaghettiWithMeatballs",
        "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
        "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
        "ingredients": [
            "spaghetti",
            "tomato sauce",
            "meatballs"
        ],
        "name": "Spaghetti with meatballs"
    }

#### 1.4.1.1.2.1. Efficient Multiple Attachments Retrieving

As noted above, retrieving document with `attachments=true` returns a large JSON object with all attachments included. When your document and files are smaller it’s ok, but if you have attached something bigger like media files (audio/video), parsing such response might be very expensive.

To solve this problem, CouchDB allows to get documents in multipart/related format:

Request:

    GET /recipes/secret?attachments=true HTTP/1.1
    Accept: multipart/related
    Host: localhost:5984

Response:

    HTTP/1.1 200 OK
    Content-Length: 538
    Content-Type: multipart/related; boundary="e89b3e29388aef23453450d10e5aaed0"
    Date: Sat, 28 Sep 2013 08:08:22 GMT
    ETag: "2-c1c6c44c4bc3c9344b037c8690468605"
    Server: CouchDB (Erlang OTP)

    --e89b3e29388aef23453450d10e5aaed0
    Content-Type: application/json

    {"_id":"secret","_rev":"2-c1c6c44c4bc3c9344b037c8690468605","_attachments":{"recipe.txt":{"content_type":"text/plain","revpos":2,"digest":"md5-HV9aXJdEnu0xnMQYTKgOFA==","length":86,"follows":true}}}
    --e89b3e29388aef23453450d10e5aaed0
    Content-Disposition: attachment; filename="recipe.txt"
    Content-Type: text/plain
    Content-Length: 86

    1. Take R
    2. Take E
    3. Mix with L
    4. Add some A
    5. Serve with X

    --e89b3e29388aef23453450d10e5aaed0--

In this response the document contains only attachments stub information and quite short while all attachments goes as separate entities which reduces memory footprint and processing overhead (you’d noticed, that attachment content goes as raw data, not in base64 encoding, right?).

### 1.4.1.1.3. Retrieving Attachments Encoding Info

By using `att_encoding_info=true` query parameter you may retrieve information about compressed attachments size and used codec.

Request:

    GET /recipes/SpaghettiWithMeatballs?att_encoding_info=true HTTP/1.1
    Accept: application/json
    Host: localhost:5984

Response:

    HTTP/1.1 200 OK
    Cache-Control: must-revalidate
    Content-Length: 736
    Content-Type: application/json
    Date: Tue, 13 Aug 2013 21:35:37 GMT
    ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
    Server: CouchDB (Erlang/OTP)

    {
        "_attachments": {
            "grandma_recipe.txt": {
                "content_type": "text/plain",
                "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
                "encoded_length": 693,
                "encoding": "gzip",
                "length": 1872,
                "revpos": 4,
                "stub": true
            },
            "my_recipe.txt": {
                "content_type": "text/plain",
                "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
                "encoded_length": 100,
                "encoding": "gzip",
                "length": 85,
                "revpos": 5,
                "stub": true
            },
            "photo.jpg": {
                "content_type": "image/jpeg",
                "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
                "length": 165504,
                "revpos": 2,
                "stub": true
            }
        },
        "_id": "SpaghettiWithMeatballs",
        "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
        "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
        "ingredients": [
            "spaghetti",
            "tomato sauce",
            "meatballs"
        ],
        "name": "Spaghetti with meatballs"
    }

### 1.4.1.1.4. Creating Multiple Attachments

To create a document with multiple attachments with single request you need just inline base64 encoded attachments data into the document body:

    {
      "_id":"multiple_attachments",
      "_attachments":
      {
        "foo.txt":
        {
          "content_type":"text\/plain",
          "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
        },

       "bar.txt":
        {
          "content_type":"text\/plain",
          "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
        }
      }
    }

Alternatively, you can upload a document with attachments more efficiently in multipart/related format. This avoids having to Base64-encode the attachments, saving CPU and bandwidth. To do this, set the Content-Type header of the `PUT /{db}/{docid}` request to multipart/related.

The first MIME body is the document itself, which should have its own Content-Type of application/json". It also should include an `_attachments` metadata object in which each attachment object has a key `follows` with value `true`.

The subsequent MIME bodies are the attachments.

Request:

    PUT /temp/somedoc HTTP/1.1
    Accept: application/json
    Content-Length: 372
    Content-Type: multipart/related;boundary="abc123"
    Host: localhost:5984
    User-Agent: HTTPie/0.6.0

    --abc123
    Content-Type: application/json

    {
        "body": "This is a body.",
        "_attachments": {
            "foo.txt": {
                "follows": true,
                "content_type": "text/plain",
                "length": 21
            },
            "bar.txt": {
                "follows": true,
                "content_type": "text/plain",
                "length": 20
            }
        }
    }

    --abc123

    this is 21 chars long
    --abc123

    this is 20 chars lon
    --abc123--

Response:

    HTTP/1.1 201 Created
    Cache-Control: must-revalidate
    Content-Length: 72
    Content-Type: application/json
    Date: Sat, 28 Sep 2013 09:13:24 GMT
    ETag: "1-5575e26acdeb1df561bb5b70b26ba151"
    Location: http://localhost:5984/temp/somedoc
    Server: CouchDB (Erlang OTP)

    {
        "id": "somedoc",
        "ok": true,
        "rev": "1-5575e26acdeb1df561bb5b70b26ba151"
    }

## 1.4.1.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:

Request:

    GET /recipes/SpaghettiWithMeatballs?revs=true  HTTP/1.1
    Accept: application/json
    Host: localhost:5984

Response:

    HTTP/1.1 200 OK
    Cache-Control: must-revalidate
    Content-Length: 584
    Content-Type: application/json
    Date: Wed, 14 Aug 2013 11:38:26 GMT
    ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
    Server: CouchDB (Erlang/OTP)

    {
        "_id": "SpaghettiWithMeatballs",
        "_rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
        "_revisions": {
            "ids": [
                "6f5ad8db0f34af24a6e0984cd1a6cfb9",
                "77fba3a059497f51ec99b9b478b569d2",
                "136813b440a00a24834f5cb1ddf5b1f1",
                "fd96acb3256302bf0dd2f32713161f2a",
                "874985bc28906155ba0e2e0538f67b05",
                "0de77a37463bf391d14283e626831f2e",
                "d795d1b924777732fdea76538c558b62",
                "917fa2381192822767f010b95b45325b"
            ],
            "start": 8
        },
        "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
        "ingredients": [
            "spaghetti",
            "tomato sauce",
            "meatballs"
        ],
        "name": "Spaghetti with meatballs"
    }

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

- ids (array): Array of valid revision IDs, in reverse order (latest first)

- start (number): Prefix number for the latest revision

## 1.4.1.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:

Request:

    GET /recipes/SpaghettiWithMeatballs?revs_info=true  HTTP/1.1
    Accept: application/json
    Host: localhost:5984

Response:

    HTTP/1.1 200 OK
    Cache-Control: must-revalidate
    Content-Length: 802
    Content-Type: application/json
    Date: Wed, 14 Aug 2013 11:40:55 GMT
    Server: CouchDB (Erlang/OTP)

    {
        "_id": "SpaghettiWithMeatballs",
        "_rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
        "_revs_info": [
            {
                "rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
                "status": "available"
            },
            {
                "rev": "7-77fba3a059497f51ec99b9b478b569d2",
                "status": "deleted"
            },
            {
                "rev": "6-136813b440a00a24834f5cb1ddf5b1f1",
                "status": "available"
            },
            {
                "rev": "5-fd96acb3256302bf0dd2f32713161f2a",
                "status": "missing"
            },
            {
                "rev": "4-874985bc28906155ba0e2e0538f67b05",
                "status": "missing"
            },
            {
                "rev": "3-0de77a37463bf391d14283e626831f2e",
                "status": "missing"
            },
            {
                "rev": "2-d795d1b924777732fdea76538c558b62",
                "status": "missing"
            },
            {
                "rev": "1-917fa2381192822767f010b95b45325b",
                "status": "missing"
            }
        ],
        "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
        "ingredients": [
            "spaghetti",
            "tomato sauce",
            "meatballs"
        ],
        "name": "Spaghetti with meatballs"
    }

The returned document contains `_revs_info` field with extended revision information, including the availability and status of each revision. This array field contains objects with following structure:

- rev (string): Full revision string

- status (string): Status of the revision. Maybe one of:

  - `available`: Revision is available for retrieving with rev query parameter

  - `missing`: Revision is not available

  - `deleted`: Revision belongs to deleted document

## 1.4.1.4. Obtaining a Specific Revision

To get a specific revision, use the `rev` argument to the request, and specify the full revision number. The specified revision of the document will be returned, including a `_rev` field specifying the revision that was requested.

Request:

    GET /recipes/SpaghettiWithMeatballs?rev=6-136813b440a00a24834f5cb1ddf5b1f1  HTTP/1.1
    Accept: application/json
    Host: localhost:5984

Response:

    HTTP/1.1 200 OK
    Cache-Control: must-revalidate
    Content-Length: 271
    Content-Type: application/json
    Date: Wed, 14 Aug 2013 11:40:55 GMT
    Server: CouchDB (Erlang/OTP)

    {
        "_id": "SpaghettiWithMeatballs",
        "_rev": "6-136813b440a00a24834f5cb1ddf5b1f1",
        "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
        "ingredients": [
            "spaghetti",
            "tomato sauce",
            "meatballs"
        ],
        "name": "Spaghetti with meatballs"
    }

### 1.4.1.4.1. Retrieving Deleted Documents

CouchDB doesn’t actually delete documents via `DELETE /{db}/{docid}`. Instead, it leaves tombstone with very basic information about the document. If you just `GET /{db}/{docid}` CouchDB returns 404 Not Found response:

Request:

    GET /recipes/FishStew  HTTP/1.1
    Accept: application/json
    Host: localhost:5984

Response:

    HTTP/1.1 404 Object Not Found
    Cache-Control: must-revalidate
    Content-Length: 41
    Content-Type: application/json
    Date: Wed, 14 Aug 2013 12:23:27 GMT
    Server: CouchDB (Erlang/OTP)

    {
        "error": "not_found",
        "reason": "deleted"
    }

However, you may retrieve document’s tombstone by using `rev` query parameter with `GET /{db}/{docid}` request:

Request:

    GET /recipes/FishStew?rev=2-056f5f44046ecafc08a2bc2b9c229e20  HTTP/1.1
    Accept: application/json
    Host: localhost:5984

Response:

    HTTP/1.1 200 OK
    Cache-Control: must-revalidate
    Content-Length: 79
    Content-Type: application/json
    Date: Wed, 14 Aug 2013 12:30:22 GMT
    ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
    Server: CouchDB (Erlang/OTP)

    {
        "_deleted": true,
        "_id": "FishStew",
        "_rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
    }

## 1.4.1.5. Updating an Existing Document

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

Request:

    PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
    Accept: application/json
    Content-Length: 258
    Content-Type: application/json
    Host: localhost:5984

    {
        "_rev": "1-917fa2381192822767f010b95b45325b",
        "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
        "ingredients": [
            "spaghetti",
            "tomato sauce",
            "meatballs"
        ],
        "name": "Spaghetti with meatballs",
        "serving": "hot"
    }

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

    PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
    Accept: application/json
    Content-Length: 258
    Content-Type: application/json
    If-Match: 1-917fa2381192822767f010b95b45325b
    Host: localhost:5984

    {
        "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
        "ingredients": [
            "spaghetti",
            "tomato sauce",
            "meatballs"
        ],
        "name": "Spaghetti with meatballs",
        "serving": "hot"
    }

Response:

    HTTP/1.1 201 Created
    Cache-Control: must-revalidate
    Content-Length: 85
    Content-Type: application/json
    Date: Wed, 14 Aug 2013 20:33:56 GMT
    ETag: "2-790895a73b63fb91dd863388398483dd"
    Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
    Server: CouchDB (Erlang/OTP)

    {
        "id": "SpaghettiWithMeatballs",
        "ok": true,
        "rev": "2-790895a73b63fb91dd863388398483dd"
    }

## 1.4.1.6. Copying from a Specific Revision

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

Request:

    COPY /recipes/SpaghettiWithMeatballs HTTP/1.1
    Accept: application/json
    Destination: SpaghettiWithMeatballs_Original
    If-Match: 1-917fa2381192822767f010b95b45325b
    Host: localhost:5984

Response:

    HTTP/1.1 201 Created
    Cache-Control: must-revalidate
    Content-Length: 93
    Content-Type: application/json
    Date: Wed, 14 Aug 2013 14:21:00 GMT
    ETag: "1-917fa2381192822767f010b95b45325b"
    Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Original
    Server: CouchDB (Erlang/OTP)

    {
        "id": "SpaghettiWithMeatballs_Original",
        "ok": true,
        "rev": "1-917fa2381192822767f010b95b45325b"
    }

## 1.4.1.7. Copying to an Existing Document

To copy to an existing document, you must specify the current revision string for the target document by appending the `rev` parameter to the Destination header string.

Request:

    COPY /recipes/SpaghettiWithMeatballs?rev=8-6f5ad8db0f34af24a6e0984cd1a6cfb9 HTTP/1.1
    Accept: application/json
    Destination: SpaghettiWithMeatballs_Original?rev=1-917fa2381192822767f010b95b45325b
    Host: localhost:5984

Response:

    HTTP/1.1 201 Created
    Cache-Control: must-revalidate
    Content-Length: 93
    Content-Type: application/json
    Date: Wed, 14 Aug 2013 14:21:00 GMT
    ETag: "2-62e778c9ec09214dd685a981dcc24074""
    Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Original
    Server: CouchDB (Erlang/OTP)

    {
        "id": "SpaghettiWithMeatballs_Original",
        "ok": true,
        "rev": "2-62e778c9ec09214dd685a981dcc24074"
    }