Skip to content

Read and write data objects from a function ​

A function runtime can read and write data objects on the same distribution through host-mediated env.document calls. Grants decide which script may touch which key, whether the object is public (visitors can GET it when a route or fallback serves it) or private (never served to visitors), and whether access is read-only or read-write.

Grants live outside the function source. Handler code cannot create, change, or bypass a grant. Setting a grant needs function.write (edge_document_grant_set or edge_document_prefix_set). document.write alone is not enough.

Function grants and private data objects are not managed in the web console yet. Use an agent or MCP.

This page assumes a distribution with at least one compiled function runtime. If not, start with Add an endpoint. Throughout, that distribution is acme-marketing (d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38) and the handler script is 01JBQZ8XKT4A9WN2CDEFGH5RM7.

1. Write a public object (when visitors should read it) ​

For a public grant on one key, the object must already exist under the public store (the same files you manage with edge_document_write).

text
On acme-marketing, store a data object menu.json with
{"title":"Lunch"} and show me the etag.
bash
edge api PUT /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/documents --input - <<'EOF'
{
        "documents": [
          {
            "path": "menu.json",
            "content": "{\"title\":\"Lunch\"}"
          }
        ]
      }
EOF
bash
curl -s -X PUT \
  https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/documents \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "documents": [
          {
            "path": "menu.json",
            "content": "{\"title\":\"Lunch\"}"
          }
        ]
      }'

The agent runs edge_document_write. This does not grant the function access yet.

2. Grant the function access ​

Pick mode read or read-write, visibility public or private, and optionally a scripts list that names script ids and read or write access. When scripts is omitted, every function on the distribution receives the mode's access. Use mode none to remove a sidecar grant.

VisibilityVisitor GET /_apiTypical use
publicYes, when mapped or via the GET fallbackShared JSON the page and a function both use
privateNo — 404 even if a route matchedNotes, drafts, counters only the function should touch

You cannot change visibility on an existing grant. Public read-write keys are served with cache-control: no-store so a cached copy does not hide writes from your function.

text
On acme-marketing, grant script 01JBQZ8XKT4A9WN2CDEFGH5RM7 read access
to the public data object menu.json.
text
On acme-marketing, set a private prefix grant on notes/ for script
01JBQZ8XKT4A9WN2CDEFGH5RM7 with read-write access.

The agent runs edge_document_grant_set or edge_document_prefix_set. A prefix grant covers every key under it, including keys the function creates later. At most 32 prefix grants and 32 scripts per sidecar grant apply; see Limits.

For private keys, seed content with edge_private_document_write after the private grant exists. Those tools read and write the private store only — not the public edge_document_* paths.

3. Call env.document from the handler ​

handler receives the stores as its second argument, env. JavaScript and Python both expose env.document (the older edge.document global is the same object). Python raises DocumentError with a .code field when the platform refuses the call.

MethodPurpose
get(key)Returns {body, etag}
put(key, body, ifMatch?)Returns {etag}. Send the previous etag as ifMatch to detect concurrent writers
list(prefix, cursor?)Returns {keys, cursor} — pages of up to 50 keys
delete(key)Returns {deleted: true}

At most eight host calls run per invocation, shared with env.kv and env.sql. Each body is capped at 1 MiB, the same as a public data object.

javascript
function handler(request, env) {
  var doc = env.document.get('menu.json');
  return {
    statusCode: 200,
    headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
    body: JSON.stringify({ menu: JSON.parse(doc.body), etag: doc.etag }),
  };
}

Common error codes on error.code (JavaScript) or DocumentError.code (Python):

CodeMeaning
deniedNo grant, script not listed, or access too weak — including get on a missing key
not_foundGrant allows the call but the object is absent (except denied-without-grant on get)
etag_mismatchifMatch did not match the stored object
etag_requiredUpdate requires an etag but none was sent
already_existsCreate conflict on a key that already exists

Map the function onto /_api with Add an endpoint. Test with edge_function_invoke before you rely on a public path.

4. Inspect grants ​

text
Show the function grant for menu.json on acme-marketing and list
all prefix grants.

The agent runs edge_document_grant_get and edge_document_prefix_get (function.read).

Next ​