Skip to content

Serve a data object ​

A data object is a file Edge stores for a distribution and can serve on /_api. Use it for flows, config and other payloads the page fetches same-origin. It is not a file in a deployment bundle.

Data objects are not managed in the web console yet. Use an agent, the CLI, or the API.

This page assumes a live distribution. If not, start with Publish your first site. Throughout, that distribution is acme-marketing (d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38).

1. Write the object ​

text
On acme-marketing, store a data object flows.json with
{"welcome":"Hello from Edge"} and show me the etag.
bash
edge api PUT /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/documents --input - <<'EOF'
{
        "documents": [
          {
            "path": "flows.json",
            "content": "{\"welcome\":\"Hello from Edge\"}"
          }
        ]
      }
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": "flows.json",
            "content": "{\"welcome\":\"Hello from Edge\"}"
          }
        ]
      }'

The agent runs edge_document_write. The HTTP body field is documents (objects is still accepted). A write can send if_match or if_none_match so two editors do not overwrite each other; the get response includes etag and version_id.

This does not change which /_api paths exist. Visitors cannot see the file until a path serves it.

Cap is 1,000 objects per distribution and 1 MiB per body. Keys are at most 256 characters and 8 segments deep. See Limits.

2. Map it (or use the GET fallback) ​

Unmapped GET /_api/flows already looks up flows.json. Map the path when you want an explicit TTL or a key that does not match that convention.

The JSON field for the endpoint map is runtime. Sending runtime replaces the whole map. If you already have other /_api paths, include them in the same update or they disappear.

text
Map GET /_api/flows on acme-marketing to the data object flows.json
with a 300 second cache. Keep every existing endpoint.
bash
edge api PATCH /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 --input - <<'EOF'
{
        "runtime": {
          "api": {
            "routes": [
              {
                "match": "/_api/flows",
                "document": "flows.json",
                "cache_ttl_seconds": 300
              }
            ]
          }
        }
      }
EOF
bash
curl -s -X PATCH \
  https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "runtime": {
          "api": {
            "routes": [
              {
                "match": "/_api/flows",
                "document": "flows.json",
                "cache_ttl_seconds": 300
              }
            ]
          }
        }
      }'

The agent runs edge_distribution_update. Data-object routes are GET-only; omit methods. Then from the page:

javascript
fetch('/_api/flows').then((r) => r.json())

Do not invent /api/flows. Unmapped POST to /_api returns 405.

3. Change it without overwriting someone else ​

Read the object first and send its etag as if_match on the next write. If another writer changed the object in between, your write fails instead of silently replacing theirs. Use if_none_match when the path must not exist yet.

Writing the same path creates a new version. A visitor can send If-None-Match with the current etag to receive 304 when the body has not changed.

4. Inspect history or roll back ​

History and rollback are MCP-only.

text
Show the version history of flows.json on acme-marketing, including
delete markers.

The agent runs edge_document_history. Each entry includes version_id, etag, size, last-modified time, and whether it is a delete marker.

text
Restore flows.json on acme-marketing to version 4dzQ… and show me the
new etag.

The agent runs edge_document_rollback. Rollback does not move an old version pointer: it copies the selected version forward as a new latest version, preserving the full history.

5. Remove it ​

To stop serving it, remove the route from runtime.api.routes (or rely on 404 once the object is deleted). The agent runs edge_document_delete.

Do not put secrets in a data object. Anything you store here can be fetched by a visitor who knows the path.

Next ​