1.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"
}

1.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
    }
]

1.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
Query Parameters:
	descending (boolean) – Return the databases in descending order by key. Default is false. endkey (json) – Stop returning databases when the specified key is reached. end_key (json) – Alias for endkey param limit (number) – Limit the number of the returned databases to the specified number. skip (number) – Skip this number of databases before starting to return the results. Default is 0. startkey (json) – Return databases starting with the specified key. start_key (json) – Alias for startkey.
Response Headers:
	Content-Type – application/json text/plain; charset=utf-8
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"
]

1.2.4. /_dbs_info¶

POST /_dbs_info¶

Returns information of a list of the specified databases in the CouchDB instance. This enables you to request information about multiple databases in a single request, in place of multiple GET /{db} requests.

Request Headers:
	Accept – application/json
Response Headers:
	Content-Type – application/json
Request JSON Object:
	keys (array) – Array of database names to be requested
Status Codes:	200 OK – Request completed successfully 400 Bad Request – Missing keys or exceeded keys in request

Request:

POST /_dbs_info HTTP/1.1
Accept: application/json
Host: localhost:5984
Content-Type: application/json

{
    "keys": [
        "animals",
        "plants"
    ]
}

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Sat, 20 Dec 2017 06:57:48 GMT
Server: CouchDB (Erlang/OTP)

[
  {
    "key": "animals",
    "info": {
      "db_name": "animals",
      "update_seq": "52232",
      "sizes": {
        "file": 1178613587,
        "external": 1713103872,
        "active": 1162451555
      },
      "purge_seq": 0,
      "other": {
        "data_size": 1713103872
      },
      "doc_del_count": 0,
      "doc_count": 52224,
      "disk_size": 1178613587,
      "disk_format_version": 6,
      "data_size": 1162451555,
      "compact_running": false,
      "cluster": {
        "q": 8,
        "n": 3,
        "w": 2,
        "r": 2
      },
      "instance_start_time": "0"
    }
  },
  {
    "key": "plants",
    "info": {
      "db_name": "plants",
      "update_seq": "303",
      "sizes": {
        "file": 3872387,
        "external": 2339,
        "active": 67475
      },
      "purge_seq": 0,
      "other": {
        "data_size": 2339
      },
      "doc_del_count": 0,
      "doc_count": 11,
      "disk_size": 3872387,
      "disk_format_version": 6,
      "data_size": 67475,
      "compact_running": false,
      "cluster": {
        "q": 8,
        "n": 3,
        "w": 2,
        "r": 2
      },
      "instance_start_time": "0"
    }
  }
]

1.2.5. /_cluster_setup¶

GET /_cluster_setup¶

Returns the status of the node or cluster, per the cluster setup wizard.

Request Headers:
	Accept – application/json text/plain
Query Parameters:
	ensure_dbs_exist (array) – List of system databases to ensure exist on the node/cluster. Defaults to ["_users","_replicator","_global_changes"].
Response Headers:
	Content-Type – application/json text/plain; charset=utf-8
Response JSON Object:
	state (string) – Current state of the node and/or cluster (see below)
Status Codes:	200 OK – Request completed successfully

The state returned indicates the current node or cluster state, and is one of the following:

• cluster_disabled: The current node is completely unconfigured.
• single_node_disabled: The current node is configured as a single (standalone) node ([cluster] n=1), but either does not have a server-level admin user defined, or does not have the standard system databases created. If the ensure_dbs_exist query parameter is specified, the list of databases provided overrides the default list of standard system databases.
• single_node_enabled: The current node is configured as a single (standalone) node, has a server-level admin user defined, and has the ensure_dbs_exist list (explicit or default) of databases created.
• cluster_enabled: The current node has [cluster] n > 1, is not bound to 127.0.0.1 and has a server-level admin user defined. However, the full set of standard system databases have not been created yet. If the ensure_dbs_exist query parameter is specified, the list of databases provided overrides the default list of standard system databases.
• cluster_finished: The current node has [cluster] n > 1, is not bound to 127.0.0.1, has a server-level admin user defined and has the ensure_dbs_exist list (explicit or default) of databases created.

Request:

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

Response:

HTTP/1.1 200 OK
X-CouchDB-Body-Time: 0
X-Couch-Request-ID: 5c058bdd37
Server: CouchDB/2.1.0-7f17678 (Erlang OTP/17)
Date: Sun, 30 Jul 2017 06:33:18 GMT
Content-Type: application/json
Content-Length: 29
Cache-Control: must-revalidate

{"state":"cluster_enabled"}

POST /_cluster_setup¶

Configure a node as a single (standalone) node, as part of a cluster, or finalise a cluster.

Request Headers:
	Accept – application/json text/plain Content-Type – application/json
Request JSON Object:
	action (string) – enable_single_node: Configure the current node as a single, standalone CouchDB server. enable_cluster: Configure the local or remote node as one node, preparing it to be joined to a new CouchDB cluster. add_node: Add the specified remote node to this cluster’s list of nodes, joining it to the cluster. finish_cluster: Finalise the cluster by creating the standard system databases. bind_address (string) – The IP address to which to bind the current node. The special value 0.0.0.0 may be specified to bind to all interfaces on the host. (enable_cluster and enable_single_node only) username (string) – The username of the server-level administrator to create. (enable_cluster and enable_single_node only), or the remote server’s administrator username (add_node) password (string) – The password for the server-level administrator to create. (enable_cluster and enable_single_node only), or the remote server’s administrator username (add_node) port (number) – The TCP port to which to bind this node (enable_cluster and enable_single_node only) or the TCP port to which to bind a remote node (add_node only). node_count (number) – The total number of nodes to be joined into the cluster, including this one. Used to determine the value of the cluster’s n, up to a maximum of 3. (enable_cluster only) remote_node (string) – The IP address of the remote node to setup as part of this cluster’s list of nodes. (enable_cluster only) remote_current_user (string) – The username of the server-level administrator authorized on the remote node. (enable_cluster only) remote_current_password (string) – The password of the server-level administrator authorized on the remote node. (enable_cluster only) host (string) – The remote node IP of the node to add to the cluster. (add_node only) ensure_dbs_exist (array) – List of system databases to ensure exist on the node/cluster. Defaults to ["_users","_replicator","_global_changes"].

No example request/response included here. For a worked example, please see The Cluster Setup API.

1.2.6. /_db_updates¶

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) – normal: Returns all historical DB changes, then closes the connection. Default. 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 (number) – Period in milliseconds after which an empty line is sent in the results. Only applicable for longpoll, continuous, and eventsource feeds. Overrides any timeout to keep the feed alive indefinitely. Default is 60000. May be true to use default value. since (string) – Return only updates since the specified sequence ID. May be the string now to begin showing only new updates.
Response Headers:
	Content-Type – application/json text/plain; charset=utf-8 Transfer-Encoding – chunked
Response JSON Object:
	results (array) – An array of database events. For longpoll and continuous modes, the entire response is the contents of the results array. last_seq (string) – The last sequence ID reported.
Status Codes:	200 OK – Request completed successfully 401 Unauthorized – CouchDB Server Administrator privileges required

The results field of database updates:

JSON Object:	db_name (string) – Database name. type (string) – A database event is one of created, updated, deleted. seq (json) – Update sequence of the event.

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, 18 Mar 2017 19:01:35 GMT
Etag: "C1KU98Y6H0LGM7EQQYL6VSL07"
Server: CouchDB/2.0.0 (Erlang OTP/17)
Transfer-Encoding: chunked
X-Couch-Request-ID: ad87efc7ff
X-CouchDB-Body-Time: 0

{
    "results":[
        {"db_name":"mailbox","type":"created","seq":"1-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZExFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4h"},
        {"db_name":"mailbox","type":"deleted","seq":"2-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZEpFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4hdQsg6vYTUncAou4-IXUPIOpA7ssCAIFHa60"},
    ],
    "last_seq": "2-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZEpFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4hdQsg6vYTUncAou4-IXUPIOpA7ssCAIFHa60"
}

1.2.7. /_membership¶

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. The endpoint is useful when setting up a cluster, see Node Management

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 /_membership 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, 11 Jul 2015 07:02:41 GMT
Server: CouchDB (Erlang/OTP)
Content-Length: 142

{
    "all_nodes": [
        "node1@127.0.0.1",
        "node2@127.0.0.1",
        "node3@127.0.0.1"
    ],
    "cluster_nodes": [
        "node1@127.0.0.1",
        "node2@127.0.0.1",
        "node3@127.0.0.1"
    ]
}

1.2.8. /_replicate¶

POST /_replicate¶

Request, configure, or stop, a replication operation.

Request Headers:
	Accept – application/json text/plain Content-Type – application/json
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 filter (string) – The name of a filter function. proxy (string) – Address of a proxy server through which replication should occur (protocol can be “http” or “socks5”) source (string/object) – Source database name or URL or an object which contains the full URL of the source database with additional parameters like headers. Eg: ‘source_db_name’ or ‘http://example.com/source_db_name’ or {“url”:”url in here”, “headers”: {“header1”:”value1”, …}} target (string/object) – Target database name or URL or an object which contains the full URL of the target database with additional parameters like headers. Eg: ‘target_db_name’ or ‘http://example.com/target_db_name’ or {“url”:”url in here”, “headers”: {“header1”:”value1”, …}}
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:	200 OK – Replication request successfully completed 202 Accepted – Continuous replication request has been accepted 400 Bad Request – Invalid JSON data 401 Unauthorized – CouchDB Server Administrator privileges required 404 Not Found – Either the source or target DB is not found or attempt to cancel unknown replication task 500 Internal Server Error – JSON specification was invalid

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
}

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

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

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

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

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

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

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

{
    "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
}

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

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

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

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

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

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

1.2.9. /_scheduler/jobs¶

GET /_scheduler/jobs¶

List of replication jobs. Includes replications created via /_replicate endpoint as well as those created from replication documents. Does not include replications which have completed or have failed to start because replication documents were malformed. Each job description will include source and target information, replication id, a history of recent event, and a few other things.

Request Headers:
	Accept – application/json
Response Headers:
	Content-Type – application/json
Query Parameters:
	limit (number) – How many results to return skip (number) – How many result to skip starting at the beginning, ordered by replication ID
Response JSON Object:
	offset (number) – How many results were skipped total_rows (number) – Total number of replication jobs id (string) – Replication ID. database (string) – Replication document database doc_id (string) – Replication document ID history (list) – Timestamped history of events as a list of objects pid (string) – Replication process ID node (string) – Cluster node where the job is running source (string) – Replication source target (string) – Replication target start_time (string) – Timestamp of when the replication was started
Status Codes:	200 OK – Request completed successfully 401 Unauthorized – CouchDB Server Administrator privileges required

Request:

GET /_scheduler/jobs 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, 29 Apr 2017 05:05:16 GMT
Server: CouchDB (Erlang/OTP)

{
    "jobs": [
        {
            "database": "_replicator",
            "doc_id": "cdyno-0000001-0000003",
            "history": [
                {
                    "timestamp": "2017-04-29T05:01:37Z",
                    "type": "started"
                },
                {
                    "timestamp": "2017-04-29T05:01:37Z",
                    "type": "added"
                }
            ],
            "id": "8f5b1bd0be6f9166ccfd36fc8be8fc22+continuous",
            "node": "node1@127.0.0.1",
            "pid": "<0.1850.0>",
            "source": "http://myserver.com/foo",
            "start_time": "2017-04-29T05:01:37Z",
            "target": "http://adm:*****@localhost:15984/cdyno-0000003/",
            "user": null
        },
        {
            "database": "_replicator",
            "doc_id": "cdyno-0000001-0000002",
            "history": [
                {
                    "timestamp": "2017-04-29T05:01:37Z",
                    "type": "started"
                },
                {
                    "timestamp": "2017-04-29T05:01:37Z",
                    "type": "added"
                }
            ],
            "id": "e327d79214831ca4c11550b4a453c9ba+continuous",
            "node": "node2@127.0.0.1",
            "pid": "<0.1757.0>",
            "source": "http://myserver.com/foo",
            "start_time": "2017-04-29T05:01:37Z",
            "target": "http://adm:*****@localhost:15984/cdyno-0000002/",
            "user": null
        }
    ],
    "offset": 0,
    "total_rows": 2
 }

1.2.10. /_scheduler/docs¶

GET /_scheduler/docs¶

List of replication document states. Includes information about all the documents, even in completed and failed states. For each document it returns the document ID, the database, the replication ID, source and target, and other information.

Request Headers:
	Accept – application/json
Response Headers:
	Content-Type – application/json
Query Parameters:
	limit (number) – How many results to return skip (number) – How many result to skip starting at the beginning, if ordered by document ID
Response JSON Object:
	offset (number) – How many results were skipped total_rows (number) – Total number of replication documents. id (string) – Replication ID, or null if state is completed or failed state (string) – One of following states (see Replication states for descriptions): initializing, running, completed, pending, crashing, error, failed database (string) – Database where replication document came from doc_id (string) – Replication document ID node (string) – Cluster node where the job is running source (string) – Replication source target (string) – Replication target start_time (string) – Timestamp of when the replication was started last_update (string) – Timestamp of last state update info (object) – May contain additional information about the state. For error states, this will be a string. For success states this will contain a JSON object (see below). error_count (number) – Consecutive errors count. Indicates how many times in a row this replication has crashed. Replication will be retried with an exponential backoff based on this number. As soon as the replication succeeds this count is reset to 0. To can be used to get an idea why a particular replication is not making progress.
Status Codes:	200 OK – Request completed successfully 401 Unauthorized – CouchDB Server Administrator privileges required

The info field of a scheduler doc:

JSON Object:

revisions_checked (number) – The count of revisions which have been checked since this replication began. missing_revisions_found (number) – The count of revisions which were found on the source, but missing from the target. docs_read (number) – The count of docs which have been read from the source. docs_written (number) – The count of docs which have been written to the target. changes_pending (number) – The count of changes not yet replicated. doc_write_failures (number) – The count of docs which failed to be written to the target. checkpointed_source_seq (object) – The source sequence id which was last successfully replicated.

Request:

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

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Sat, 29 Apr 2017 05:10:08 GMT
Server: Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "docs": [
        {
            "database": "_replicator",
            "doc_id": "cdyno-0000001-0000002",
            "error_count": 0,
            "id": "e327d79214831ca4c11550b4a453c9ba+continuous",
            "info": null,
            "last_updated": "2017-04-29T05:01:37Z",
            "node": "node2@127.0.0.1",
            "proxy": null,
            "source": "http://myserver.com/foo",
            "start_time": "2017-04-29T05:01:37Z",
            "state": "running",
            "target": "http://adm:*****@localhost:15984/cdyno-0000002/"
        },
        {
            "database": "_replicator",
            "doc_id": "cdyno-0000001-0000003",
            "error_count": 0,
            "id": "8f5b1bd0be6f9166ccfd36fc8be8fc22+continuous",
            "info": null,
            "last_updated": "2017-04-29T05:01:37Z",
            "node": "node1@127.0.0.1",
            "proxy": null,
            "source": "http://myserver.com/foo",
            "start_time": "2017-04-29T05:01:37Z",
            "state": "running",
            "target": "http://adm:*****@localhost:15984/cdyno-0000003/"
        }
    ],
    "offset": 0,
    "total_rows": 2
}

GET /_scheduler/docs/{replicator_db}¶

Get information about replication documents from a replicator database. The default replicator database is _replicator but other replicator databases can exist if their name ends with the suffix /_replicator.

Note

As a convenience slashes (/) in replicator db names do not have to be escaped. So /_scheduler/docs/other/_replicator is valid and equivalent to /_scheduler/docs/other%2f_replicator

Request Headers:
	Accept – application/json
Response Headers:
	Content-Type – application/json
Query Parameters:
	limit (number) – How many results to return skip (number) – How many result to skip starting at the beginning, if ordered by document ID
Response JSON Object:
	offset (number) – How many results were skipped total_rows (number) – Total number of replication documents. id (string) – Replication ID, or null if state is completed or failed state (string) – One of following states (see Replication states for descriptions): initializing, running, completed, pending, crashing, error, failed database (string) – Database where replication document came from doc_id (string) – Replication document ID node (string) – Cluster node where the job is running source (string) – Replication source target (string) – Replication target start_time (string) – Timestamp of when the replication was started last_update (string) – Timestamp of last state update info (object) – May contain additional information about the state. For error states, this will be a string. For success states this will contain a JSON object (see below). error_count (number) – Consecutive errors count. Indicates how many times in a row this replication has crashed. Replication will be retried with an exponential backoff based on this number. As soon as the replication succeeds this count is reset to 0. To can be used to get an idea why a particular replication is not making progress.
Status Codes:	200 OK – Request completed successfully 401 Unauthorized – CouchDB Server Administrator privileges required

The info field of a scheduler doc:

JSON Object:

revisions_checked (number) – The count of revisions which have been checked since this replication began. missing_revisions_found (number) – The count of revisions which were found on the source, but missing from the target. docs_read (number) – The count of docs which have been read from the source. docs_written (number) – The count of docs which have been written to the target. changes_pending (number) – The count of changes not yet replicated. doc_write_failures (number) – The count of docs which failed to be written to the target. checkpointed_source_seq (object) – The source sequence id which was last successfully replicated.

Request:

GET /_scheduler/docs/other/_replicator HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Sat, 29 Apr 2017 05:10:08 GMT
Server: Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "docs": [
        {
            "database": "other/_replicator",
            "doc_id": "cdyno-0000001-0000002",
            "error_count": 0,
            "id": "e327d79214831ca4c11550b4a453c9ba+continuous",
            "info": null,
            "last_updated": "2017-04-29T05:01:37Z",
            "node": "node2@127.0.0.1",
            "proxy": null,
            "source": "http://myserver.com/foo",
            "start_time": "2017-04-29T05:01:37Z",
            "state": "running",
            "target": "http://adm:*****@localhost:15984/cdyno-0000002/"
        }
    ],
    "offset": 0,
    "total_rows": 1
}

GET /_scheduler/docs/{replicator_db}/{docid}¶

Note

As a convenience slashes (/) in replicator db names do not have to be escaped. So /_scheduler/docs/other/_replicator is valid and equivalent to /_scheduler/docs/other%2f_replicator

Request Headers:
	Accept – application/json
Response Headers:
	Content-Type – application/json
Response JSON Object:
	id (string) – Replication ID, or null if state is completed or failed state (string) – One of following states (see Replication states for descriptions): initializing, running, completed, pending, crashing, error, failed database (string) – Database where replication document came from doc_id (string) – Replication document ID node (string) – Cluster node where the job is running source (string) – Replication source target (string) – Replication target start_time (string) – Timestamp of when the replication was started last_update (string) – Timestamp of last state update info (object) – May contain additional information about the state. For error states, this will be a string. For success states this will contain a JSON object (see below). error_count (number) – Consecutive errors count. Indicates how many times in a row this replication has crashed. Replication will be retried with an exponential backoff based on this number. As soon as the replication succeeds this count is reset to 0. To can be used to get an idea why a particular replication is not making progress.
Status Codes:	200 OK – Request completed successfully 401 Unauthorized – CouchDB Server Administrator privileges required

The info field of a scheduler doc:

JSON Object:

revisions_checked (number) – The count of revisions which have been checked since this replication began. missing_revisions_found (number) – The count of revisions which were found on the source, but missing from the target. docs_read (number) – The count of docs which have been read from the source. docs_written (number) – The count of docs which have been written to the target. changes_pending (number) – The count of changes not yet replicated. doc_write_failures (number) – The count of docs which failed to be written to the target. checkpointed_source_seq (object) – The source sequence id which was last successfully replicated. Request:

GET /_scheduler/docs/other/_replicator/cdyno-0000001-0000002 HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Sat, 29 Apr 2017 05:10:08 GMT
Server: Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "database": "other/_replicator",
    "doc_id": "cdyno-0000001-0000002",
    "error_count": 0,
    "id": "e327d79214831ca4c11550b4a453c9ba+continuous",
    "info": null,
    "last_updated": "2017-04-29T05:01:37Z",
    "node": "node2@127.0.0.1",
    "proxy": null,
    "source": "http://myserver.com/foo",
    "start_time": "2017-04-29T05:01:37Z",
    "state": "running",
    "target": "http://adm:*****@localhost:15984/cdyno-0000002/"
}

1.2.11. /_node/{node-name}/_stats¶

GET /_node/{node-name}/_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.

The literal string _local serves as an alias for the local node name, so for all stats URLs, {node-name} may be replaced _local, to interact with the local node’s statistics.

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 /_node/_local/_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)

{
  "value": {
    "min": 0,
    "max": 0,
    "arithmetic_mean": 0,
    "geometric_mean": 0,
    "harmonic_mean": 0,
    "median": 0,
    "variance": 0,
    "standard_deviation": 0,
    "skewness": 0,
    "kurtosis": 0,
    "percentile": [
      [
        50,
        0
      ],
      [
        75,
        0
      ],
      [
        90,
        0
      ],
      [
        95,
        0
      ],
      [
        99,
        0
      ],
      [
        999,
        0
      ]
    ],
    "histogram": [
      [
        0,
        0
      ]
    ],
    "n": 0
  },
  "type": "histogram",
  "desc": "length of a request inside CouchDB without MochiWeb"
}

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 sufficient detail to determine units.

Statistics are reported by ‘group’. The statistics are divided into the following top-level sections:

• couch_log: Logging subsystem
• couch_replicator: Replication scheduler and subsystem
• couchdb: Primary CouchDB database operations
• fabric: Cluster-related operations
• global_changes: Global changes feed
• mem3: Node membership-related statistics
• pread: CouchDB file-related exceptions
• rexi: Cluster internal RPC-related statistics

The type of the statistic is included in the type field, and is one of the following:

• counter: Monotonically increasing counter, resets on restart
• histogram: Binned set of values with meaningful subdivisions
• gauge: Single numerical value that can go up and down

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 within the couchdb section for the target node, you can use:

GET /_node/_local/_stats/couchdb/request_time HTTP/1.1

This returns an entire statistics object, as with the full request, but containing only the requested individual statistic.

1.2.12. /_node/{node-name}/_system¶

GET /_node/{node-name}/_system¶

The _system resource returns a JSON object containing various system-level 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.

The literal string _local serves as an alias for the local node name, so for all stats URLs, {node-name} may be replaced _local, to interact with the local node’s statistics.

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 /_node/_local/_system 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)

{
  "uptime": 259,
  "memory": {
  ...
}

These statistics are generally intended for CouchDB developers only.

1.2.13. /_node/{node-name}/_restart¶

POST /_node/{node-name}/_restart¶

This API is to facilitate integration testing only it is not meant to be used in production

Status Codes:	200 OK – Request completed successfully

1.2.14. /_utils¶

GET /_utils¶

Accesses the built-in Fauxton administration interface for CouchDB.

Response Headers:
	Location – New URI location
Status Codes:	301 Moved Permanently – Redirects to GET /_utils/

GET /_utils/¶

Response Headers:
	Content-Type – text/html Last-Modified – Static files modification timestamp
Status Codes:	200 OK – Request completed successfully

1.2.15. /_up¶

GET /_up¶

Confirms that the server is up, running, and ready to respond to requests. If maintenance_mode is true or nolb, the endpoint will return a 404 response.

Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – Request completed successfully 404 Not Found – The server is unavaialble for requests at this time.

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 16
Content-Type: application/json
Date: Sat, 17 Mar 2018 04:46:26 GMT
Server: CouchDB/2.2.0-f999071ec (Erlang OTP/19)
X-Couch-Request-ID: c57a3b2787
X-CouchDB-Body-Time: 0

{"status":"ok"}

1.2.16. /_uuids¶

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:	200 OK – Request completed successfully 400 Bad Request – Requested more UUIDs than is allowed to retrieve

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/_node/nonode@nohost/_config/uuids/algorithm HTTP/1.1
Content-Type: application/json
Accept: */*

"random"

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

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

1.2.17. /favicon.ico¶

GET /favicon.ico¶

Binary content for the favicon.ico site icon.

Response Headers:
	Content-Type – image/x-icon
Status Codes:	200 OK – Request completed successfully 404 Not Found – The requested content could not be found