Skip to content

Proxy a backend ​

A backend proxy endpoint forwards a /_api path to one HTTPS URL. The page keeps a same-origin fetch; Edge dials the origin, enforces the timeout and size cap, and refuses private addresses.

Proxy endpoints 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).

Map the path ​

The origin must be https with a DNS hostname. IP literals, localhost, and private, link-local or metadata addresses are refused. {splat} copies the rest of the visitor path into the upstream URL; it cannot appear in the hostname.

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
On acme-marketing, proxy POST and PUT /_api/crm/* to
https://crm.example.com/hooks/{splat}. Keep every existing endpoint.
Do not cache the responses.
bash
edge api PATCH /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 --input - <<'EOF'
{
        "runtime": {
          "api": {
            "routes": [
              {
                "match": "/_api/crm/*",
                "proxy": "https://crm.example.com/hooks/{splat}",
                "methods": ["POST", "PUT"],
                "cache_ttl_seconds": 0
              }
            ]
          }
        }
      }
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/crm/*",
                "proxy": "https://crm.example.com/hooks/{splat}",
                "methods": ["POST", "PUT"],
                "cache_ttl_seconds": 0
              }
            ]
          }
        }
      }'

The agent runs edge_distribution_update. Default cache TTL for a proxy is 0. Then from the page, fetch("/_api/crm/lead", { method: "POST", headers: { "content-type": "application/json", "x-amz-content-sha256": "<hex>" }, body }) — the hash is the lowercase hex SHA-256 of that body, or the edge returns 400. Visitor cookies are not forwarded. Redirects are not followed.

A connection failure, an origin that never answers, or an unsafe address returns 502. Timeout is 10 seconds. See Limits.

Credentials and streaming ​

To attach a secret the visitor must never see, add proxy_auth — typically { "target": "header", "name": "Authorization", "value": "Bearer …" }. Prefer a header; a query parameter puts the secret in the upstream URL, which logs and traces can record. At most five credentials per distribution. Reads come back as { configured: true } without the value; send that shape back to keep the stored secret, or send a new value to rotate it.

For an origin that streams (SSE, chunked chat), set "proxy_mode": "stream". A stream is not retried once status and headers have gone to the visitor. If the origin dies mid-body, the visitor may already have seen 200 and then a truncated payload.

Buffered GET/HEAD retries a connection failure or 502/503/504 once, inside the same timeout.

Next ​