Skip to content

Endpoints ​

An endpoint is a /_api path on a distribution. The console labels this surface Endpoints. Each path has exactly one target:

KindRoute fieldServes
Data objectdocumentA stored JSON (or other text) file you wrote with edge_document_write
Backend proxyproxyAn HTTPS origin you maintain
Function runtimewasmCompiled code you created with edge_function_create
FilefilePublic 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 platform lambda allowlist; GET /_api/__health is provided without a route). object is still accepted as an alias of document.
  • methods is an allowlist of GET, HEAD, POST, PUT, PATCH, DELETE. A rejected method returns 405 with Allow. Data-object routes are GET-only and file routes answer GET and HEAD only — omit methods on 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 /_api path.
  • Default cache TTL is 60 seconds for data objects, 0 for proxies and function runtimes.
  • POST and PUT with a body must send x-amz-content-sha256 as 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 is documents (objects is still accepted).
  • Version history and rollback are MCP-only: edge_document_history and edge_document_rollback.
  • Writes accept if_match / if_none_match against the object's etag.
  • Unmapped GET /_api/widgets serves the data object widgets.json when no route matched. Map explicitly when you need a different key or TTL.
  • Unmapped POST /_api returns 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 still GET them 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, and edge_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 https only. 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) or stream. 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_auth attaches a credential you store — typically an Authorization header. 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.

json
{ "match": "/_api/exports/*", "file": "exports/", "cache_ttl_seconds": 300 }
  • On a /* match, file is a key prefix ending in / and the rest of the path is appended. Without /*, file is 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:

json
{ "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.

json
{
  "runtime": {
    "uploads": {
      "apply": {
        "fields": {
          "resume": { "types": ["application/pdf"], "max_bytes": 104857600, "max_files": 1 }
        }
      }
    }
  }
}
KeyRule
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
typesRequired, no duplicates, each from the list below
max_bytes1 to 5,368,709,120 (5 GiB). Default 104,857,600 (100 MiB)
max_files1 to 10. Default 1
Per submissionThe fields' max_files add up to at most 10, and max_files × max_bytes to at most 10 GiB

Allowed types:

KindType strings
Documentsapplication/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.presentationml.presentation
Archives and dataapplication/zip, text/plain, text/csv, application/json
Imagesimage/png, image/jpeg, image/gif, image/webp, image/heic, image/avif
Videovideo/mp4, video/quicktime, video/webm
Audioaudio/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.

RequestBodyAnswer
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.

StatusBodyCause
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:

reasonCause
not_an_uploadNot an upload id (upl_ and 26 characters)
too_manyMore ids than max_files
duplicateThe same id twice
invalidIssued to another session, form or field; already used; or its file was rejected
not_uploadedThe 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.

statusMeaning
scanningNot settled
cleanReadable and downloadable
rejectedreason malware, type_mismatch or size_mismatch; the file is deleted
scan_failedNo 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.

See also ​