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
On acme-marketing, store a data object flows.json with
{"welcome":"Hello from Edge"} and show me the etag.edge api PUT /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/documents --input - <<'EOF'
{
"documents": [
{
"path": "flows.json",
"content": "{\"welcome\":\"Hello from Edge\"}"
}
]
}
EOFcurl -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.
Map GET /_api/flows on acme-marketing to the data object flows.json
with a 300 second cache. Keep every existing endpoint.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
}
]
}
}
}
EOFcurl -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:
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.
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.
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.