9.2.1. /

GET /

Accessing the root of a CouchDB instance returns meta information about the instance. The response is a JSON structure containing information about the server, including a welcome message and the version of the server.

Request Headers:
 
  • Accept
    • application/json
    • text/plain
Response Headers:
 
  • Content-Type
    • application/json
    • text/plain; charset=utf-8
Status Codes:
  • 200 OK – Request completed successfully

Request:

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

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 179
Content-Type: application/json
Date: Sat, 10 Aug 2013 06:33:33 GMT
Server: CouchDB (Erlang/OTP)

{
    "couchdb": "Welcome",
    "uuid": "85fb71bf700c17267fef77535820e371",
    "vendor": {
        "name": "The Apache Software Foundation",
        "version": "1.3.1"
    },
    "version": "1.3.1"
}

9.2.2. /_active_tasks

GET /_active_tasks

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

Request Headers:
 
  • Accept
    • application/json
    • text/plain
Response Headers:
 
  • Content-Type
    • application/json
    • text/plain; charset=utf-8
Response JSON Object:
 
  • changes_done (number) – Processed changes
  • database (string) – Source database
  • pid (string) – Process ID
  • progress (number) – Current percentage progress
  • started_on (number) – Task start time as unix timestamp
  • status (string) – Task status message
  • task (string) – Task name
  • total_changes (number) – Total changes to process
  • type (string) – Operation Type
  • updated_on (number) – Unix timestamp of last operation update
Status Codes:
  • 200 OK – Request completed successfully
  • 401 Unauthorized – CouchDB Server Administrator privileges required

Request:

GET /_active_tasks HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 1690
Content-Type: application/json
Date: Sat, 10 Aug 2013 06:37:31 GMT
Server: CouchDB (Erlang/OTP)

[
    {
        "changes_done": 64438,
        "database": "mailbox",
        "pid": "<0.12986.1>",
        "progress": 84,
        "started_on": 1376116576,
        "total_changes": 76215,
        "type": "database_compaction",
        "updated_on": 1376116619
    },
    {
        "changes_done": 14443,
        "database": "mailbox",
        "design_document": "c9753817b3ba7c674d92361f24f59b9f",
        "pid": "<0.10461.3>",
        "progress": 18,
        "started_on": 1376116621,
        "total_changes": 76215,
        "type": "indexer",
        "updated_on": 1376116650
    },
    {
        "changes_done": 5454,
        "database": "mailbox",
        "design_document": "_design/meta",
        "pid": "<0.6838.4>",
        "progress": 7,
        "started_on": 1376116632,
        "total_changes": 76215,
        "type": "indexer",
        "updated_on": 1376116651
    },
    {
        "checkpointed_source_seq": 68585,
        "continuous": false,
        "doc_id": null,
        "doc_write_failures": 0,
        "docs_read": 4524,
        "docs_written": 4524,
        "missing_revisions_found": 4524,
        "pid": "<0.1538.5>",
        "progress": 44,
        "replication_id": "9bc1727d74d49d9e157e260bb8bbd1d5",
        "revisions_checked": 4524,
        "source": "mailbox",
        "source_seq": 154419,
        "started_on": 1376116644,
        "target": "http://mailsrv:5984/mailbox",
        "type": "replication",
        "updated_on": 1376116651
    }
]

9.2.3. /_all_dbs

GET /_all_dbs

Returns a list of all the databases in the CouchDB instance.

Request Headers:
 
  • Accept
    • application/json
    • text/plain
Response Headers:
 
  • Content-Type
    • application/json
    • text/plain; charset=utf-8
Query Parameters:
 
  • limit (number) – limit the number of databases in the list
  • skip (number) – skip N elements from the list
Status Codes:
  • 200 OK – Request completed successfully

Request:

GET /_all_dbs HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 52
Content-Type: application/json
Date: Sat, 10 Aug 2013 06:57:48 GMT
Server: CouchDB (Erlang/OTP)

[
   "_users",
   "contacts",
   "docs",
   "invoices",
   "locations"
]

9.2.4. /_db_updates

New in version 1.4.

GET /_db_updates

Returns a list of all database events in the CouchDB instance.

Request Headers:
 
  • Accept
    • application/json
    • text/plain
Query Parameters:
 
  • feed (string) –
    • longpoll: Closes the connection after the first event.
    • continuous: Send a line of JSON per event. Keeps the socket open until timeout.
    • eventsource: Like, continuous, but sends the events in EventSource format.
  • timeout (number) – Number of seconds until CouchDB closes the connection. Default is 60.
  • heartbeat (boolean) – Whether CouchDB will send a newline character (\n) on timeout. Default is true.
Response Headers:
 
Response JSON Object:
 
  • db_name (string) – Database name
  • ok (boolean) – Event operation status
  • type (string) – A database event is one of created, updated, deleted
Status Codes:
  • 200 OK – Request completed successfully
  • 401 Unauthorized – CouchDB Server Administrator privileges required

Request:

GET /_db_updates HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Sat, 10 Aug 2013 07:02:41 GMT
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "db_name": "mailbox",
    "ok": true,
    "type": "created"
}

9.2.5. /_log

GET /_log

Gets the CouchDB log, equivalent to accessing the local log file of the corresponding CouchDB instance.

Request Headers:
 
Query Parameters:
 
  • bytes (number) – Bytes to be returned. Default is 1000.
  • offset (number) – Offset in bytes where the log tail should be started. Default is 0.
Response Headers:
 
Status Codes:
  • 200 OK – Request completed successfully
  • 401 Unauthorized – CouchDB Server Administrator privileges required

Request:

GET /_log HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

[Wed, 27 Oct 2010 10:49:42 GMT] [info] [<0.23338.2>] 192.168.0.2 - - 'PUT' /authdb 401
[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200
[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200
[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200
[Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200

If you want to pick out specific parts of the log information you can use the bytes argument, which specifies the number of bytes to be returned, and offset, which specifies where the reading of the log should start, counted back from the end. For example, if you use the following request:

GET /_log?bytes=500&offset=2000

Reading of the log will start at 2000 bytes from the end of the log, and 500 bytes will be shown.

How bytes/offset works?

CouchDB reads specified amount of bytes from the end of log file, jumping to offset bytes towards the beginning of the file first:

 Log File    FilePos
 ----------
|          |  10
|          |  20
|          |  30
|          |  40
|          |  50
|          |  60
|          |  70 -- Bytes = 20  --
|          |  80                 | Chunk
|          |  90 -- Offset = 10 --
|__________| 100

9.2.6. /_replicate

POST /_replicate

Request, configure, or stop, a replication operation.

Request Headers:
 
Request JSON Object:
 
  • cancel (boolean) – Cancels the replication
  • continuous (boolean) – Configure the replication to be continuous
  • create_target (boolean) – Creates the target database. Required administrator’s privileges on target server.
  • doc_ids (array) – Array of document IDs to be synchronized
  • proxy (string) – Address of a proxy server through which replication should occur (protocol can be “http” or “socks5”)
  • source (string) – Source database name or URL
  • target (string) – Target database name or URL
Response Headers:
 
  • Content-Type
    • application/json
    • text/plain; charset=utf-8
Response JSON Object:
 
  • history (array) – Replication history (see below)
  • ok (boolean) – Replication status
  • replication_id_version (number) – Replication protocol version
  • session_id (string) – Unique session ID
  • source_last_seq (number) – Last sequence number read from source database
Status Codes:

The specification of the replication request is controlled through the JSON content of the request. The JSON should be an object with the fields defining the source, target and other options.

The Replication history is an array of objects with following structure:

JSON Object:
  • doc_write_failures (number) – Number of document write failures
  • docs_read (number) – Number of documents read
  • docs_written (number) – Number of documents written to target
  • end_last_seq (number) – Last sequence number in changes stream
  • end_time (string) – Date/Time replication operation completed in RFC 2822 format
  • missing_checked (number) – Number of missing documents checked
  • missing_found (number) – Number of missing documents found
  • recorded_seq (number) – Last recorded sequence number
  • session_id (string) – Session ID for this replication operation
  • start_last_seq (number) – First sequence number in changes stream
  • start_time (string) – Date/Time replication operation started in RFC 2822 format

Request

POST /_replicate HTTP/1.1
Accept: application/json
Content-Length: 36
Content-Type: application/json
Host: localhost:5984

{
    "source": "db_a",
    "target": "db_b"
}

Response

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 692
Content-Type: application/json
Date: Sun, 11 Aug 2013 20:38:50 GMT
Server: CouchDB (Erlang/OTP)

{
    "history": [
        {
            "doc_write_failures": 0,
            "docs_read": 10,
            "docs_written": 10,
            "end_last_seq": 28,
            "end_time": "Sun, 11 Aug 2013 20:38:50 GMT",
            "missing_checked": 10,
            "missing_found": 10,
            "recorded_seq": 28,
            "session_id": "142a35854a08e205c47174d91b1f9628",
            "start_last_seq": 1,
            "start_time": "Sun, 11 Aug 2013 20:38:50 GMT"
        },
        {
            "doc_write_failures": 0,
            "docs_read": 1,
            "docs_written": 1,
            "end_last_seq": 1,
            "end_time": "Sat, 10 Aug 2013 15:41:54 GMT",
            "missing_checked": 1,
            "missing_found": 1,
            "recorded_seq": 1,
            "session_id": "6314f35c51de3ac408af79d6ee0c1a09",
            "start_last_seq": 0,
            "start_time": "Sat, 10 Aug 2013 15:41:54 GMT"
        }
    ],
    "ok": true,
    "replication_id_version": 3,
    "session_id": "142a35854a08e205c47174d91b1f9628",
    "source_last_seq": 28
}

Replication Operation

The aim of the replication is that at the end of the process, all active documents on the source database are also in the destination database and all documents that were deleted in the source databases are also deleted (if they exist) on the destination database.

Replication can be described as either push or pull replication:

  • Pull replication is where the source is the remote CouchDB instance, and the target is the local database.

    Pull replication is the most useful solution to use if your source database has a permanent IP address, and your destination (local) database may have a dynamically assigned IP address (for example, through DHCP). This is particularly important if you are replicating to a mobile or other device from a central server.

  • Push replication is where the source is a local database, and target is a remote database.

Specifying the Source and Target Database

You must use the URL specification of the CouchDB database if you want to perform replication in either of the following two situations:

  • Replication with a remote database (i.e. another instance of CouchDB on the same host, or a different host)
  • Replication with a database that requires authentication

For example, to request replication between a database local to the CouchDB instance to which you send the request, and a remote database you might use the following request:

POST http://couchdb:5984/_replicate
Content-Type: application/json
Accept: application/json

{
   "source" : "recipes",
   "target" : "http://coucdb-remote:5984/recipes",
}

In all cases, the requested databases in the source and target specification must exist. If they do not, an error will be returned within the JSON object:

{
   "error" : "db_not_found"
   "reason" : "could not open http://couchdb-remote:5984/ol1ka/",
}

You can create the target database (providing your user credentials allow it) by adding the create_target field to the request object:

POST http://couchdb:5984/_replicate
Content-Type: application/json
Accept: application/json

{
   "create_target" : true
   "source" : "recipes",
   "target" : "http://couchdb-remote:5984/recipes",
}

The create_target field is not destructive. If the database already exists, the replication proceeds as normal.

Single Replication

You can request replication of a database so that the two databases can be synchronized. By default, the replication process occurs one time and synchronizes the two databases together. For example, you can request a single synchronization between two databases by supplying the source and target fields within the request JSON content.

POST http://couchdb:5984/_replicate
Accept: application/json
Content-Type: application/json

{
   "source" : "recipes",
   "target" : "recipes-snapshot",
}

In the above example, the databases recipes and recipes-snapshot will be synchronized. These databases are local to the CouchDB instance where the request was made. The response will be a JSON structure containing the success (or failure) of the synchronization process, and statistics about the process:

{
   "ok" : true,
   "history" : [
      {
         "docs_read" : 1000,
         "session_id" : "52c2370f5027043d286daca4de247db0",
         "recorded_seq" : 1000,
         "end_last_seq" : 1000,
         "doc_write_failures" : 0,
         "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT",
         "start_last_seq" : 0,
         "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT",
         "missing_checked" : 0,
         "docs_written" : 1000,
         "missing_found" : 1000
      }
   ],
   "session_id" : "52c2370f5027043d286daca4de247db0",
   "source_last_seq" : 1000
}

Continuous Replication

Synchronization of a database with the previously noted methods happens only once, at the time the replicate request is made. To have the target database permanently replicated from the source, you must set the continuous field of the JSON object within the request to true.

With continuous replication changes in the source database are replicated to the target database in perpetuity until you specifically request that replication ceases.

POST http://couchdb:5984/_replicate
Accept: application/json
Content-Type: application/json

{
   "continuous" : true
   "source" : "recipes",
   "target" : "http://couchdb-remote:5984/recipes",
}

Changes will be replicated between the two databases as long as a network connection is available between the two instances.

Note

Two keep two databases synchronized with each other, you need to set replication in both directions; that is, you must replicate from source to target, and separately from target to source.

Canceling Continuous Replication

You can cancel continuous replication by adding the cancel field to the JSON request object and setting the value to true. Note that the structure of the request must be identical to the original for the cancellation request to be honoured. For example, if you requested continuous replication, the cancellation request must also contain the continuous field.

For example, the replication request:

POST http://couchdb:5984/_replicate
Content-Type: application/json
Accept: application/json

{
   "source" : "recipes",
   "target" : "http://couchdb-remote:5984/recipes",
   "create_target" : true,
   "continuous" : true
}

Must be canceled using the request:

POST http://couchdb:5984/_replicate
Accept: application/json
Content-Type: application/json

{
    "cancel" : true,
    "continuous" : true
    "create_target" : true,
    "source" : "recipes",
    "target" : "http://couchdb-remote:5984/recipes",
}

Requesting cancellation of a replication that does not exist results in a 404 error.

9.2.7. /_restart

POST /_restart

Restarts the CouchDB instance. You must be authenticated as a user with administration privileges for this to work.

Request Headers:
 
Response Headers:
 
  • Content-Type
    • application/json
    • text/plain; charset=utf-8
Status Codes:

Request:

POST /_restart HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 202 Accepted
Cache-Control: must-revalidate
Content-Length: 12
Content-Type: application/json
Date: Sat, 10 Aug 2013 11:33:50 GMT
Server: CouchDB (Erlang/OTP)

{
    "ok": true
}

9.2.8. /_stats

GET /_stats

The _stats resource returns a JSON object containing the statistics for the running server. The object is structured with top-level sections collating the statistics for a range of entries, with each individual statistic being easily identified, and the content of each statistic is self-describing

Request Headers:
 
  • Accept
    • application/json
    • text/plain
Response Headers:
 
  • Content-Type
    • application/json
    • text/plain; charset=utf-8
Status Codes:
  • 200 OK – Request completed successfully

Request:

GET /_stats/couchdb/request_time HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 187
Content-Type: application/json
Date: Sat, 10 Aug 2013 11:41:11 GMT
Server: CouchDB (Erlang/OTP)

{
    "couchdb": {
        "request_time": {
            "current": 21.0,
            "description": "length of a request inside CouchDB without MochiWeb",
            "max": 19.0,
            "mean": 7.0,
            "min": 1.0,
            "stddev": 10.392,
            "sum": 21.0
        }
    }
}

The fields provide the current, minimum and maximum, and a collection of statistical means and quantities. The quantity in each case is not defined, but the descriptions below provide

The statistics are divided into the following top-level sections:

couchdb

Describes statistics specific to the internals of CouchDB

Statistic ID Description Unit
auth_cache_hits Number of authentication cache hits number
auth_cache_misses Number of authentication cache misses number
database_reads Number of times a document was read from a database number
database_writes Number of times a database was changed number
open_databases Number of open databases number
open_os_files Number of file descriptors CouchDB has open number
request_time Length of a request inside CouchDB without MochiWeb milliseconds

httpd_request_methods

Statistic ID Description Unit
COPY Number of HTTP COPY requests number
DELETE Number of HTTP DELETE requests number
GET Number of HTTP GET requests number
HEAD Number of HTTP HEAD requests number
POST Number of HTTP POST requests number
PUT Number of HTTP PUT requests number

httpd_status_codes

Statistic ID Description Unit
200 Number of HTTP 200 OK responses number
201 Number of HTTP 201 Created responses number
202 Number of HTTP 202 Accepted responses number
301 Number of HTTP 301 Moved Permanently responses number
304 Number of HTTP 304 Not Modified responses number
400 Number of HTTP 400 Bad Request responses number
401 Number of HTTP 401 Unauthorized responses number
403 Number of HTTP 403 Forbidden responses number
404 Number of HTTP 404 Not Found responses number
405 Number of HTTP 405 Method Not Allowed responses number
409 Number of HTTP 409 Conflict responses number
412 Number of HTTP 412 Precondition Failed responses number
500 Number of HTTP 500 Internal Server Error responses number

httpd

Statistic ID Description Unit
bulk_requests Number of bulk requests number
clients_requesting_changes Number of clients for continuous _changes number
requests Number of HTTP requests number
temporary_view_reads Number of temporary view reads number
view_reads Number of view reads number

You can also access individual statistics by quoting the statistics sections and statistic ID as part of the URL path. For example, to get the request_time statistics, you can use:

GET /_stats/couchdb/request_time

This returns an entire statistics object, as with the full request, but containing only the request individual statistic. Hence, the returned structure is as follows:

{
   "couchdb" : {
      "request_time" : {
         "stddev" : 7454.305,
         "min" : 1,
         "max" : 34185,
         "current" : 34697.803,
         "mean" : 1652.276,
         "sum" : 34697.803,
         "description" : "length of a request inside CouchDB without MochiWeb"
      }
   }
}

9.2.9. /_utils

GET /_utils

Accesses the built-in Futon administration interface for CouchDB.

Response Headers:
 
Status Codes:
GET /_utils/
Response Headers:
 
Status Codes:
  • 200 OK – Request completed successfully

9.2.10. /_uuids

Changed in version 1.5.1.

GET /_uuids

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

Request Headers:
 
  • Accept
    • application/json
    • text/plain
Query Parameters:
 
  • count (number) – Number of UUIDs to return. Default is 1.
Response Headers:
 
  • Content-Type
    • application/json
    • text/plain; charset=utf-8
  • ETag – Response hash
Status Codes:

Request:

GET /_uuids?count=10 HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Content-Length: 362
Content-Type: application/json
Date: Sat, 10 Aug 2013 11:46:25 GMT
ETag: "DGRWWQFLUDWN5MRKSLKQ425XV"
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Pragma: no-cache
Server: CouchDB (Erlang/OTP)

{
    "uuids": [
        "75480ca477454894678e22eec6002413",
        "75480ca477454894678e22eec600250b",
        "75480ca477454894678e22eec6002c41",
        "75480ca477454894678e22eec6003b90",
        "75480ca477454894678e22eec6003fca",
        "75480ca477454894678e22eec6004bef",
        "75480ca477454894678e22eec600528f",
        "75480ca477454894678e22eec6005e0b",
        "75480ca477454894678e22eec6006158",
        "75480ca477454894678e22eec6006161"
    ]
}

The UUID type is determined by the UUID algorithm setting in the CouchDB configuration.

The UUID type may be changed at any time through the Configuration API. For example, the UUID type could be changed to random by sending this HTTP request:

PUT http://couchdb:5984/_config/uuids/algorithm
Content-Type: application/json
Accept: */*

"random"

You can verify the change by obtaining a list of UUIDs:

{
   "uuids" : [
      "031aad7b469956cf2826fcb2a9260492",
      "6ec875e15e6b385120938df18ee8e496",
      "cff9e881516483911aa2f0e98949092d",
      "b89d37509d39dd712546f9510d4a9271",
      "2e0dbf7f6c4ad716f21938a016e4e59f"
   ]
}

9.2.11. /favicon.ico

GET /favicon.ico

Binary content for the favicon.ico site icon.

Response Headers:
 
Status Codes:
  • 200 OK – Request completed successfully
  • 404 Not Found – The requested content could not be found