---
title: Document Access with Edge Server
description: You can create, read, update, and delete documents in a keyspace
  using the REST API's document operations.
pubDate: 2026-08-17T09:53:44.266Z
antora:
  editUrl: https://github.com/couchbaselabs/docs-couchbase-lite-edge-server/edit/release/1.0/modules/rest-based-access/pages/document-access.adoc
  xref: xref:1.0@couchbase-edge-server:rest-based-access:document-access.adoc[]
---

[Consult the llms.txt file for a full list of contents](/llms.txt)
[View original HTML](/couchbase-edge-server/1.0/rest-based-access/document-access.html)

# Document Access with Edge Server

> You can create, read, update, and delete documents in a keyspace using the REST API's document operations. 

## [](#scopes-and-collections)Scopes and Collections

Within a database, documents are organized using scopes and collections. A database contains one or more scopes, and each scope may contain one or more collections. All documents are stored within a collection.

Each database contains a default scope called `_default`, which contains a default collection, also called `_default`. A database may contain other named, non-default scopes and collections as required.

For more information on scopes and collections, see [Manage Scopes and Collections](../../../couchbase-lite/current/c/scopes-collections-manage.md).

## [](#keyspace-references)Keyspace References

When working with documents, you must specify the database, scope and collection where the documents are stored. To do this, you must provide a keyspace reference to the REST API.

* For a named scope and collection, the keyspace reference consists of the database name, followed by the scope name and the collection name, separated by periods (`.`). For example, `travel-sample.inventory.airports`.
* For a named collection within the default scope, you can omit the scope name from the keyspace reference. For example, `travel-sample.my_records` refers to the `my_records` collection within the default scope in the `travel-sample` database.
* For the default scope and collection, you can omit both the scope name and the collection name from the keyspace reference. For example, `travel-sample` refers to the default collection within the default scope in the `travel-sample` database.

## [](#document-structure)Document Structure

In Edge Server, the content of each document is a JSON object. Each document has metadata, which includes the document ID and revision number. Documents can have subdocuments and binary attachments.

For more information on documents, see [Documents](../../../couchbase-lite/current/c/document.md). For more information on binary attachments, see [Blobs](../../../couchbase-lite/current/c/blob.md).

## [](#examples)Examples

In the command line examples:

* `$USER` and `$PASSWORD` are the credentials for Couchbase Edge Server.
* `$CERT` is the name and path to a TLS certificate file, for example `cert.cer`.
* `$HOST` and `$PORT` are the host and port to connect to Couchbase Edge Server, for example `localhost:59840`.
* `$DOCID` is the ID of a document, for example `~SCH2oNtKFMBdcO-_sUhBmn`.
* `$REV` is a revision number, for example `1-22855783cf597c31c37ec3815d8027f3706ef6f9`.

Note that the following cURL examples use a self-signed TLS server certificate. In production, you are strongly recommended to use a TLS certificate generated by a well-known authority.

### [](#create-a-document)Create a Document

The following request creates a new document in the specified keyspace.

HTTP Request

```sh
curl --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport" \
  --json '{
  "type": "airport",
  "country": "United Kingdom",
  "icao": "EGOV",
  "airportname": "Anglesey Airport",
  "city": "Valley",
  "faa": "VLY",
  "tz": "Europe/London"
}'
```

The response is a JSON object similar to the following. In this case, Edge Server generates an ID for the document automatically.

HTTP Response

```json
{
  "ok": true,
  "id": "~SCH2oNtKFMBdcO-_sUhBmn",
  "rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}
```

You can use the generated document ID to read, update, or delete the same document. You must use the document revision number for concurrency control.

### [](#read-a-document)Read a Document

The following request gets the specified document in the specified keyspace.

HTTP Request

```sh
curl --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport/$DOCID"
```

The response is a JSON object similar to the following. Note that the response contains the document ID and revision number, as well as the document content.

HTTP Response

```json
{
  "_id": "~SCH2oNtKFMBdcO-_sUhBmn",
  "_rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9",
  "type": "airport",
  "country": "United Kingdom",
  "icao": "EGOV",
  "airportname": "Anglesey Airport",
  "city": "Valley",
  "faa": "VLY",
  "tz": "Europe/London"
}
```

### [](#update-a-document)Update a Document

The following request checks whether the specified document within the specified keyspace has the expected revision number. If so, it adds a `geo` subdocument to the document.

This ensures that you're applying your update to the latest revision of the document, in cases where the document may be updated by other processes concurrently.

HTTP Request

```sh
curl -XPUT $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport/$DOCID/geo?rev=$REV" \
  --json '{
  "lat": 53.248056,
  "lon": -4.535278,
  "alt": 37
}'
```

If the revision number of the document matches, the response is a JSON object similar to the following. Note that the revision has been updated.

HTTP Response

```json
{
  "ok": true,
  "id": "~SCH2oNtKFMBdcO-_sUhBmn",
  "rev": "2-51cb776222e4a366e8961e1c9fc09edddc5b0fa1"
}
```

If the revision number does not match, the request returns a `409` error. If this happens, get the latest revision number for the document and try again.

### [](#delete-a-document)Delete a Document

The following request checks whether the specified document within the specified keyspace has the expected revision number. If so, it deletes the document.

This ensures that you're deleting the latest revision of the document, in cases where the document may be updated by other processes concurrently.

HTTP Request

```sh
curl -XDELETE $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport/$DOCID?rev=$REV"
```

If the revision number of the document matches, the document is deleted. Note that Edge Server returns a revision number for the deletion itself.

HTTP Response

```json
{
  "ok": true,
  "id": "~SCH2oNtKFMBdcO-_sUhBmn",
  "rev": "3-b76bfea54ebb8e0337998d1ab591d9b19e238551"
}
```

If the revision number does not match, the request returns a `409` error. If this happens, get the latest revision number for the document and try again.

## [](#see-also)See Also

* [Edge Server REST API](rest-api-landing.md)
* [Get Started with the Edge Server REST API](rest-api-start.md)
* [Database Operations with Edge Server](database-operations.md)
* [Monitor Changes with Edge Server](changes-feed.md)
* [Run Queries with Edge Server](queries-api.md)
* [Manage Replication with Edge Server](replication.md)
* [Edge Server Public REST API](../public-api-reference/index.md)