Endpoints
An endpoint is a /_api path on a distribution. The console labels this surface Endpoints. Each path has exactly one target:
| Kind | Route field | Serves |
|---|---|---|
| Data object | document | A stored JSON (or other text) file you wrote with edge_document_write |
| Backend proxy | proxy | An HTTPS origin you maintain |
| Function runtime | wasm | Compiled code you created with edge_function_create |
| File | file | Public files a function wrote with env.file |
Do not invent /api/*. Match paths must start with /_api. First match wins.
The JSON field for the map is runtime. Sending runtime replaces the whole map — include every path you still want. An update that only sends runtime compiles onto the live /_api lane: no preview URL and no promote.
Endpoints are not managed in the web console yet. Write data objects and map paths through an agent, the CLI, or the API.
Shared rules
- A route sets exactly one of
document,file,proxy,wasm(or the platformlambdaallowlist;GET /_api/__healthis provided without a route).objectis still accepted as an alias ofdocument. methodsis an allowlist ofGET,HEAD,POST,PUT,PATCH,DELETE. A rejected method returns 405 withAllow. Data-object routes are GET-only and file routes answerGETandHEADonly — omitmethodson both./_api/_jobs/and/_api/_uploads/are reserved by the platform; a route cannot match them./_upload/{form_id}is a separate platform lane for form uploads, not a/_apipath.- Default cache TTL is 60 seconds for data objects, 0 for proxies and function runtimes.
POSTandPUTwith a body must sendx-amz-content-sha256as the lowercase hex SHA-256 of that body, or the edge returns 400.- At most 100 proxy endpoints per distribution, and 1,000 data objects. See Limits.
Data objects
Write the file, then map it — or rely on the unmapped GET fallback.
- Tools:
edge_document_list,edge_document_get,edge_document_write,edge_document_delete. HTTP:/v1/distributions/{id}/documents. The write body field isdocuments(objectsis still accepted). - Version history and rollback are MCP-only:
edge_document_historyandedge_document_rollback. - Writes accept
if_match/if_none_matchagainst the object'setag. - Unmapped
GET /_api/widgetsserves the data objectwidgets.jsonwhen no route matched. Map explicitly when you need a different key or TTL. - Unmapped
POST /_apireturns 405. - Do not store secrets in data objects; they are served to visitors.
See Serve a data object.
Function grants and private objects
Maintainers grant function runtimes access to data objects separately from writing the JSON file. Grants are MCP-only: edge_document_grant_get, edge_document_grant_set, edge_document_prefix_get, edge_document_prefix_set (function.read / function.write). A sidecar grant covers one key; a prefix grant covers every key under it.
- Public grants point at objects in the public store (
edge_document_*). Visitors can stillGETthem when a route or fallback serves the key. - Private grants use the private store. Visitors always receive 404 on those keys. Seed and manage private JSON with
edge_private_document_list,edge_private_document_get,edge_private_document_write, andedge_private_document_delete(function.read/function.write). - Public read-write keys are served with
cache-control: no-store.
Inside a granted function, use env.document — see Read and write data objects from a function.
Backend proxies
Forward a path to one HTTPS URL.
- Scheme
httpsonly. Host must be a DNS name — not an IP literal, localhost, or a private / link-local / metadata address. {splat}copies the unmatched path suffix into the upstream URL. It cannot appear in the hostname.- Visitor cookies are not forwarded. Redirects are not followed. Timeout is 10 seconds.
- Modes:
buffered(default) orstream. A stream is not retried once headers have been sent; a visitor may see 200 then a truncated body if the upstream dies mid-flight. - Optional
proxy_authattaches a credential you store — typically anAuthorizationheader. It never goes to the visitor. Prefer a header over a query parameter. - Connection failure to the upstream returns 502.
See Proxy a backend.
Function runtimes
Your handler, compiled to WebAssembly. Creating it does not change the live site; mapping wasm to a script id does. Languages are javascript, python, rust, tinygo, c and assemblyscript. See Function runtimes and Add an endpoint.
Files
file serves files a function runtime wrote to the public file store. Private files are never served by a route; they leave only through a short-lived link the function asks for.
{ "match": "/_api/exports/*", "file": "exports/", "cache_ttl_seconds": 300 }- On a
/*match,fileis a key prefix ending in/and the rest of the path is appended. Without/*,fileis one key, such as"brand/logo.png". - Images, PDF, plain text, CSV, JSON, and common audio and video render in the browser. Every other type — including HTML, SVG and scripts — downloads as an attachment inside a sandbox content security policy, so a stored file can never run on your site's origin.
- Files up to 4 MiB are served directly. Larger files redirect to a download link valid for five minutes.
- A prefix a function can write is served with
cache-control: no-store.
See Store and serve files from a function.
Background routes
"background": true on a wasm route answers 202 at once and runs the function for up to five minutes:
{ "match": "/_api/reports/build", "wasm": "01M3RD5T2C8V7X1N4K6P9Q2W5Z", "methods": ["POST"], "background": true }The response is {"job_id", "status": "queued", "status_url"}. GET /_api/_jobs/{job_id} returns status (queued, running, succeeded or failed), the function's response as result once it succeeded, or error_code if it failed. A request body is capped at 192 KiB, and at most five background runs per distribution are active at once (a sixth gets 429). See Generate large files in the background.
Form uploads
runtime.uploads lets a form take files. It is set with the same distribution update as the /_api map, compiles with it, and goes live when the update compiles: no preview and no promote. Sending runtime replaces api and uploads together.
{
"runtime": {
"uploads": {
"apply": {
"fields": {
"resume": { "types": ["application/pdf"], "max_bytes": 104857600, "max_files": 1 }
}
}
}
}
}| Key | Rule |
|---|---|
Form id (apply) | 1–64 characters: letters, digits, ., _, -. At most 20 forms per distribution |
Field name (resume) | 1–64 characters: letters, digits, _, -. Not edge_s. At most 10 fields per form |
types | Required, no duplicates, each from the list below |
max_bytes | 1 to 5,368,709,120 (5 GiB). Default 104,857,600 (100 MiB) |
max_files | 1 to 10. Default 1 |
| Per submission | The fields' max_files add up to at most 10, and max_files × max_bytes to at most 10 GiB |
Allowed types:
| Kind | Type strings |
|---|---|
| Documents | application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.presentationml.presentation |
| Archives and data | application/zip, text/plain, text/csv, application/json |
| Images | image/png, image/jpeg, image/gif, image/webp, image/heic, image/avif |
| Video | video/mp4, video/quicktime, video/webm |
| Audio | audio/mpeg, audio/mp4, audio/wav, audio/ogg |
HTML, SVG, scripts and executables cannot be accepted.
The upload lane
Every call carries the visitor session as edge_s, a JSON body field or the edge_s cookie, and it must be the session that later calls /_submit.
| Request | Body | Answer |
|---|---|---|
POST /_upload/{form_id} | {"field", "name", "type", "size"} | A ticket. Up to 100 MiB: {"mode": "single", "upload_id", "url", "fields", "expires_at"}, valid 10 minutes. Larger: {"mode": "multipart", "upload_id", "part_size", "part_count", "parts": [{"n", "length", "url"}], "expires_at"}, valid one hour |
POST /_upload/{form_id}/{upload_id}/parts | {"from": 101} | The next 100 part URLs |
POST /_upload/{form_id}/{upload_id}/complete | {"parts": [{"n", "etag"}]} | {"upload_id", "status": "uploaded"} |
A single ticket is a multipart/form-data POST to url with every entry of fields, then the file last. A multipart ticket's parts are 16 MiB (the last is the remainder); each URL takes a PUT of exactly length bytes. The size declared for the ticket is pinned.
| Status | Body | Cause |
|---|---|---|
| 400 | {"error": "invalid_upload", "field", "reason"} | reason type, size or name (empty, over 255 characters, or a slash or control character) |
| 400 | {"error": "session_required"} | No edge_s |
| 403 | {"error": "quota_exceeded"} | The organization uploaded 100 GiB or 50,000 files this month |
| 404 | {"error": "not_found"} | No policy for this form or field |
| 429 | {"error": "rate_limited"} | 20 tickets a minute per IP address, or 50 a day per session |
Submitting upload ids
/_submit/{form_id} takes upload ids as the values of upload fields, an array for several. File parts on /_submit are refused with 400. A value that is not usable is 400 {"error": "invalid_upload", "field", "reason"} and nothing is stored:
reason | Cause |
|---|---|
not_an_upload | Not an upload id (upl_ and 26 characters) |
too_many | More ids than max_files |
duplicate | The same id twice |
invalid | Issued to another session, form or field; already used; or its file was rejected |
not_uploaded | The ticket was issued but no file arrived |
The stored submission and the form.submitted event carry files: [{"field", "upload_id", "name", "type", "size", "status"}].
Scanning
Each attached file is scanned for malware and its first bytes are checked against the declared type.
status | Meaning |
|---|---|
scanning | Not settled |
clean | Readable and downloadable |
rejected | reason malware, type_mismatch or size_mismatch; the file is deleted |
scan_failed | No verdict after one retry; never readable |
PDF, Word (.docx), plain text and CSV files up to 200 MiB get extracted text, up to 1 MiB, for agents. form.file.scanned is sent once for each attached file when its scan settles. An upload that is never attached is deleted after a day.
See Accept file uploads on a form and Let an agent read form submissions.