Edge Server is a lightweight standalone database for resource-constrained edge. It exposes a RESTful interface that enables you to get database information, perform document operations, run SQL++ queries, and manage changes feeds and replication.
Edge Server enables you to access one or more databases. Within each database, documents are stored in keyspaces. Each keyspace maps to a collection, which is stored in a scope within the database. For details, see Database Operations with Edge Server.
{- "couchdb": "Welcome",
- "vendor": {
- "name": "Couchbase Edge Server",
- "version": "1.0.0 (37; )"
}, - "version": "CouchbaseEdgeServer/1.0.0 (37; ) CouchbaseLiteCore/0.0.0-EE (770a516a19d505b7+403e27d509bb1131)"
}Retrieves information about a database or keyspace.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
{- "db_name": "travel-sample",
- "db_uuid": "8478be31c9674c499c07edd4e3115de7",
- "collections": {
- "inventory.airline": {
- "doc_count": 1,
- "update_seq": 1
}, - "inventory.airport": {
- "doc_count": 1980,
- "update_seq": 1980
}, - "inventory.landmark": {
- "doc_count": 0,
- "update_seq": 0
}
}
}You can create, read, update, and delete documents in a keyspace using the REST API's document operations. For details, see Document Access with Edge Server.
Creates a document with an automatically-generated document ID.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| property name* additional property | any |
{- "type": "airport",
- "country": "United Kingdom",
- "icao": "EGOV",
- "airportname": "Anglesey Airport",
- "city": "Valley",
- "faa": "VLY",
- "tz": "Europe/London"
}{- "ok": true,
- "id": "~SCH2oNtKFMBdcO-_sUhBmn",
- "rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}Returns all documents in the database, based on the specified query parameters.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| descending | boolean Default: false Reverses sort order (descending document ID) |
| include_docs | boolean Include the body associated with each document. |
| keys | Array of strings An array of document ID strings to filter by. |
| limit | number This limits the number of result rows returned. Using a value of |
| skip | number Offset into the result rows returned. Combined with |
| startkey | string Return records starting with the specified key. |
| endkey | string Stop returning records when this key is reached. |
{- "rows": [
- {
- "key": "string",
- "id": "string",
- "value": {
- "rev": "string",
- "cv": "string"
}
}
], - "total_rows": 0,
- "update_seq": 0
}Returns all documents in the database, based on the parameters specified in the request body.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| descending | boolean Default: false Reverses sort order (descending document ID) |
| include_docs | boolean Default: true Adds body of each doc |
| keys | Array of strings Limits results to the specified document IDs |
| limit | number Limits number of results |
| skip | number Offset into results |
| startkey | string Document ID to start at |
| endkey | string Document ID to end at (max value, or min if descending) |
{- "descending": false,
- "include_docs": true,
- "keys": [
- "string"
], - "limit": 0,
- "skip": 0,
- "startkey": "string",
- "endkey": "string"
}{- "rows": [
- {
- "key": "string",
- "id": "string",
- "value": {
- "rev": "string",
- "cv": "string"
}
}
], - "total_rows": 0,
- "update_seq": 0
}Returns a status code indicating whether any documents exist.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| include_docs | boolean Include the body associated with each document. |
| keys | Array of strings An array of document ID strings to filter by. |
| startkey | string Return records starting with the specified key. |
| endkey | string Stop returning records when this key is reached. |
| limit | number This limits the number of result rows returned. Using a value of |
{- "error": "string",
- "reason": "string"
}Allows multiple documented to be created, updated or deleted in bulk.
To create a new document, add the body as an object in the docs array.
A document ID is generated by Edge Server unless _id is specified.
To update an existing document, provide the document ID (_id) and revision ID (_rev) as well as the new body values.
To delete an existing document, provide the document ID (_id), revision ID (_rev), and set the deletion flag (_deleted) to true.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| new_edits | boolean Default: true This controls whether to assign new revision identifiers to new edits ( |
required | Array of objects |
{- "new_edits": true,
- "docs": [
- {
- "_id": "FooBar",
- "foo": "bar"
}, - {
- "_id": "AliceSettings",
- "_rev": "5-832a6db48ed130adadede928aee54576",
- "FailedLoginAttempts": 7
}, - {
- "_id": "BobSettings",
- "_rev": "1-fa76ba41ee5fdfee1b91fc478ed09e59",
- "_deleted": true
}
]
}[- {
- "id": "FooBar",
- "rev": "1-cd809becc169215072fd567eebd8b8de"
}, - {
- "id": "AliceSettings",
- "rev": "6-b3e8dcf825b71ccee112f3572ec4323c"
}, - {
- "id": "BobSettings",
- "rev": "2-5145e1086bb8d1d71a531e9f6b543c58"
}
]Retrieves a document from the database by its document ID.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| docid required | string Example: doc1 The document ID to run the operation against. |
| rev | string Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58 The document revision to target. |
| revs_from | Array of strings Trims the revision history to stop at the first revision in the provided list. If no match is found, the revisions are trimmed to the |
| revs_limit | integer Maximum number of revisions to return for each document. |
{- "_id": "~SCH2oNtKFMBdcO-_sUhBmn",
- "_rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9",
- "type": "airport",
- "country": "United States",
- "faa": "LAX"
}Creates the specified document, if it does not already exist. If the specified document does exist, this request makes a new revision for the existing document. A revision ID must be provided if targeting an existing document.
You must specify a document ID for this endpoint.
To let Edge Server generate the ID, use the POST /{db}/ endpoint.
If the document already exists, the document content is replaced by the provided request body. Any existing fields which are not specified by the request body are removed in the new revision.
The maximum size for a document is 20MB.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| docid required | string Example: doc1 The document ID to run the operation against. |
| roundtrip | boolean Block until document has been received by change cache. |
| rev | string Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58 The document revision to target. |
| If-Match | string The revision ID to target. |
| _id required | string document ID |
| _rev required | string revision ID of the document |
| property name* additional property | any |
{- "_id": "~SCH2oNtKFMBdcO-_sUhBmn",
- "_rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9",
- "type": "airport",
- "country": "United States",
- "faa": "LAX"
}{- "ok": true,
- "id": "~SCH2oNtKFMBdcO-_sUhBmn",
- "rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}Deletes a document from the keyspace. A new revision is created so the database can track the deletion in synchronized copies.
A revision ID is required, either in the header or in the query parameters.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| docid required | string Example: doc1 The document ID to run the operation against. |
| rev | string Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58 The document revision to target. |
| If-Match | string The revision ID to target. |
{- "ok": true,
- "id": "~SCH2oNtKFMBdcO-_sUhBmn",
- "rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}Returns a status code indicating whether the document exists or not.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| docid required | string Example: doc1 The document ID to run the operation against. |
| rev | string Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58 The document revision to target. |
| revs_from | Array of strings Trims the revision history to stop at the first revision in the provided list. If no match is found, the revisions are trimmed to the |
| revs_limit | integer Maximum number of revisions to return for each document. |
{- "error": "string",
- "reason": "string"
}Retrieves a sub-document associated with the document.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| docid required | string Example: doc1 The document ID to run the operation against. |
| key required | string The key of the object containing the sub-document. |
| rev | string Example: rev=2-5145e1086bb8d1d71a531e9f6b543c58 The document revision to target. |
{ }Adds or updates a sub-document associated with the document. If the document does not exist, it is created and the sub-document is added to it.
If the sub-document already exists, the content of the existing sub-document is replaced in the new revision.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| docid required | string Example: doc1 The document ID to run the operation against. |
| key required | string The key of the object containing the sub-document. |
| rev | string The existing document revision ID to modify. Required only when modifying an existing document. |
The sub-document to add or modify in the document
| property name* additional property | any |
{ }{- "ok": true,
- "id": "~SCH2oNtKFMBdcO-_sUhBmn",
- "rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}Deletes a sub-document associated with the document.
If the sub-document exists, the sub-document is removed from the document.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| docid required | string Example: doc1 The document ID to run the operation against. |
| key required | string The key of the object containing the sub-document. |
| rev | string The existing document revision ID to modify. |
{- "ok": true,
- "id": "~SCH2oNtKFMBdcO-_sUhBmn",
- "rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}The replicate endpoint enables you to synchronize Edge Server with another server, for example Sync Gateway or Couchbase Capella App Services. For details, see Manage Replication with Edge Server.
[- {
- "task_id": 1,
- "age_secs": 893,
- "type": "replication",
- "error": {
- "error": "Unknown hostname \\\"myofflineappservice.apps.cloud.couchbase.com\\\"",
- "x-litecore-domain": 5,
- "x-litecore-code": 2
}, - "source": "wss://myofflineappservice.apps.cloud.couchbase.com:4984/travel-sample",
- "target": "travel-sample",
- "updated_on": 1741027601,
- "status": "Offline"
}
]Instructs Edge Server to initiate replication with another server, e.g. Sync Gateway.
| source | string The source database name or URL |
| target | string The destination database name or URL |
| bidirectional | boolean Default: false Set to |
| continuous | boolean Default: false Set to |
| channels | Array of strings unique Channel filter (incompatible with 'collections') |
| doc_ids | Array of strings unique Document IDs to replicate (incompatible with 'collections') |
object Extra HTTP headers; keys are header names, values are header values | |
Array of strings or object | |
| trusted_root_certs | string The certificate data of an additional root certificate to be trusted |
| pinned_cert | string The certificate data of the server certificate |
object Configuration for authentication to a remote server. Either for replication, or a proxy. | |
object (ProxyConfig) Configuration of a proxy to use during replication. |
{- "source": "string",
- "target": "string",
- "bidirectional": false,
- "continuous": false,
- "channels": [
- "string"
], - "doc_ids": [
- "string"
], - "headers": {
- "property1": "string",
- "property2": "string"
}, - "collections": [
- "string"
], - "trusted_root_certs": "string",
- "pinned_cert": "string",
- "auth": {
- "user": "string",
- "password": "string",
- "openid_token": "string",
- "tls_client_cert": "string",
- "tls_client_cert_key": "string",
- "session_cookie": "string"
}, - "proxy": {
- "type": "HTTP",
- "host": "string",
- "port": 0,
- "auth": {
- "user": "string",
- "password": "string",
- "openid_token": "string",
- "tls_client_cert": "string",
- "tls_client_cert_key": "string"
}
}
}{- "ok": true,
- "task_id": 0
}Gets the status of the replication task with the given ID.
| taskid required | number Example: 1234 The ID of an active replication task. |
{- "task_id": 1,
- "age_secs": 893,
- "type": "replication",
- "error": {
- "error": "Unknown hostname \\\"myofflineappservice.apps.cloud.couchbase.com\\\"",
- "x-litecore-domain": 5,
- "x-litecore-code": 2
}, - "source": "wss://myofflineappservice.apps.cloud.couchbase.com:4984/travel-sample",
- "target": "travel-sample",
- "updated_on": 1741027601,
- "status": "Offline"
}You can monitor changes in a keyspace using the keyspaces's changes feed. For details, see Monitor Changes with Edge Server.
Retrieves a sorted list of changes made to documents in the database, in time order of application. Each document appears at most once, ordered by its most recent change, regardless of how many times it has been changed.
This request can be used to listen for update and modifications to the database for post processing or synchronization. A continuously connected changes feed is a reasonable approach for generating a real-time log for most applications.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| limit | integer Maximum number of changes to return. |
| since | string Starts the results from the change immediately after the given sequence ID. Sequence IDs should be considered opaque; they come from the last_seq property of a prior response. |
| style | string Default: "main_only" Enum: "main_only" "all_docs" Controls whether to return the current winning revision ( |
| active_only | boolean Default: "false" Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed. |
| include_docs | boolean Include the body associated with each document. |
| revocations | boolean If true, revocation messages are sent on the changes feed. |
| filter | string Enum: "sync_gateway/bychannel" "_doc_ids" Set a filter to either filter by channels or document IDs. |
| channels | string A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the |
| doc_ids | Array of strings A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the |
| heartbeat | integer >= 25000 Default: 0 The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to |
| timeout | integer [ 0 .. 900000 ] Default: 300000 This is the maximum period (in milliseconds) to wait for a change before the response is sent, even if there are no results. This is only applicable for |
| feed | string Default: "normal" Enum: "longpoll" "continuous" "sse" The type of changes feed to use. |
{- "results": [
- {
- "seq": 0,
- "id": "~XEltbV2jxLN04FDFsZED5_",
- "changes": [
- {
- "rev": "1-22f5be403d75646a0758fab6731d7fa87c197666"
}
]
}, - {
- "seq": 1,
- "id": "~AxF827yGbOQprwFMNaotw2",
- "changes": [
- {
- "rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}
]
}
], - "last_seq": 1
}Retrieves a sorted list of changes made to documents in the database, in time order of application. Each document appears at most once, ordered by its most recent change, regardless of how many times it has been changed.
This request can be used to listen for update and modifications to the database for post processing or synchronization. A continuously connected changes feed is a reasonable approach for generating a real-time log for most applications.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| limit | string Maximum number of changes to return. |
| style | string Controls whether to return the current winning revision ( |
| active_only | string Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed. |
| include_docs | boolean Include the body associated with each document. |
| revocations | string If true, revocation messages are sent on the changes feed. |
| filter | string Set a filter to either filter by channels or document IDs. |
| channels | string A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the |
| doc_ids | string A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the |
| heartbeat | string The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to |
| timeout | string This is the maximum period (in milliseconds) to wait for a change before the response is sent, even if there are no results. This is only applicable for |
| feed | string The type of changes feed to use. |
{- "limit": "string",
- "style": "string",
- "active_only": "string",
- "include_docs": true,
- "revocations": "string",
- "filter": "string",
- "channels": "string",
- "doc_ids": "string",
- "heartbeat": "string",
- "timeout": "string",
- "feed": "string"
}{- "results": [
- {
- "seq": 0,
- "id": "~XEltbV2jxLN04FDFsZED5_",
- "changes": [
- {
- "rev": "1-22f5be403d75646a0758fab6731d7fa87c197666"
}
]
}, - {
- "seq": 1,
- "id": "~AxF827yGbOQprwFMNaotw2",
- "changes": [
- {
- "rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}
]
}
], - "last_seq": 1
}You can run SQL++ queries in a keyspace using the keyspace's query endpoint. For details, see Run Queries with Edge Server.
Runs an ad-hoc query.
Only possible when the database's enable_adhoc_queries property is true.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| query required | string SQL++ Query string |
object Query parameters |
{- "query": "string",
- "parameters": { }
}{- "_": {
- "id": 7630,
- "type": "airport",
- "country": "United States",
- "faa": "MPI",
- "tz": "America/Los_Angeles"
}
}Runs a pre-defined query as named by the database configuration's query object. If the query has parameters, they should be passed as query parameters, like ?key=value.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| name required | string Name of the query as defined in the database configuration. |
{- "_": {
- "id": 7630,
- "type": "airport",
- "country": "United States",
- "faa": "MPI",
- "tz": "America/Los_Angeles"
}
}Runs a pre-defined query as named by the database configuration's query object. If the query has parameters, they should be passed as JSON object in the request body.
| keyspace required | string Examples:
The keyspace to run the operation against. A keyspace is a dot-separated string, comprised of a database name, and optionally a named scope and collection. |
| name required | string Name of the query as defined in the database configuration. |
| property name* additional property | any |
{ }{- "_": {
- "id": 7630,
- "type": "airport",
- "country": "United States",
- "faa": "MPI",
- "tz": "America/Los_Angeles"
}
}