Add an endpoint
An endpoint is a /_api path on a distribution. It can run a function runtime, serve a data object, or proxy a backend you maintain. The console labels this surface Endpoints. The kinds are listed in Endpoints.
This page adds a function runtime — your handler, compiled to WebAssembly and run in a sandbox for one request at a time. Creating it does not change the live site. Mapping it onto an endpoint does.
Function runtimes are not managed in the web console yet, and they have no HTTP create API. Direct an agent. Attaching the public path is the exception: that is a distribution update, which you can also do with curl.
This page assumes you already have a live distribution. If not, start with Publish your first site. Throughout, that distribution is acme-marketing (d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38).
1. Write one file
Source must be a single self-contained file. Edge does not run npm or pip during the build, so import and require fail unless you bundled the library yourself.
This tutorial uses JavaScript. The handler receives {method, path, body} and returns {statusCode, headers, body}. body is a string or null. path never includes a query string. console.log and console.error go to the log, not to the visitor.
function handler(request, env) {
return {
statusCode: 200,
headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
body: JSON.stringify({
ok: true,
method: request.method,
path: request.path
})
};
}To include a library, bundle locally first:
esbuild echo.js --bundle --format=iife --outfile=bundle.jsUse iife, not esm. An export in the submitted source is a build error.
The other languages are python, rust, tinygo, c and assemblyscript. Python uses the same handler(request, env) shape. The compiled languages read one JSON object from stdin and write one JSON envelope to stdout. Language ABIs, toolchains and fetch rules are in Function runtimes. Ask your agent to start from the platform template for that language.
2. Create it
On the acme-marketing distribution, create a JavaScript function runtime
from echo.js. Do not map a public /_api path yet. Tell me the script id
and when the build succeeds.The agent runs edge_function_create. The reply is immediate: a script_id (a ULID), status: pending, and a job_id. The live site is unchanged.
This tutorial uses 01M2QG8K4N7R9T1V3W5X7Y9ZAB as the script id. Yours will be different.
3. Wait for the build
Ask the agent to poll until the build is done. It runs edge_function_get.
succeeded— you can invoke it.failed— readbuild_log. It names the line in your source. Fix the file and update; do not create a second function runtime for the same handler.
A mapped path serves 503 until a build has succeeded. That is why this page invokes before it publishes a URL.
4. Try it without a URL
Invoke script 01M2QG8K4N7R9T1V3W5X7Y9ZAB on acme-marketing with GET
/_api/echo and show me the body, stderr, fuel and memory.The agent runs edge_function_invoke. Invoke talks to the runner directly. It does not consult the endpoint map, so a missing /_api/echo mapping is not a failure, and a path's methods list does not apply.
Default input, if you omit it, is GET /_api/_invoke with no body. You can pass {method, path, body}, plus body_encoding: "base64" for a binary test body (Return a file from a function). Headers, cookies, query strings and auth are refused — the sandbox never receives them.
5. Put it on /_api
This is the step that can change what visitors see. Start from a distribution that is already live, as in Publish your first site.
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/echo on acme-marketing to script
01M2QG8K4N7R9T1V3W5X7Y9ZAB. Keep every existing endpoint.
Do not promote a new deployment; this is an endpoints update.edge api PATCH /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 --input - <<'EOF'
{
"runtime": {
"api": {
"routes": [
{
"match": "/_api/echo",
"wasm": "01M2QG8K4N7R9T1V3W5X7Y9ZAB",
"methods": ["GET"],
"cache_ttl_seconds": 0
}
]
}
}
}
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/echo",
"wasm": "01M2QG8K4N7R9T1V3W5X7Y9ZAB",
"methods": ["GET"],
"cache_ttl_seconds": 0
}
]
}
}
}'The agent runs edge_distribution_update. An update that only sends runtime compiles onto the live /_api lane. There is no preview URL and no promote step. Function runtimes default to cache_ttl_seconds: 0 so one visitor's answer is not served to the next.
Match paths must start with /_api. Do not invent /api/*.
Then open https://acme-marketing.edge.deca-dev.com/_api/echo. From a page on the same origin, fetch("/_api/echo") is enough. POST and PUT with a body must also send x-amz-content-sha256 as the lowercase hex SHA-256 of that body, or the edge returns 400.
6. Read what it printed
Show the last 20 log lines for script 01M2QG8K4N7R9T1V3W5X7Y9ZAB
on acme-marketing.The agent runs edge_function_logs. Rows cover visitor requests, your invokes, and hooks that run the function runtime, newest first, kept for 7 days. Stdout that is a valid response envelope is dropped — that text was the visitor's body. Request bodies, query strings, headers and cookies are never stored.
Do not print personal data. If the handler logs a visitor field, that field is in the capture.
Change it, or take it down
Updating source keeps the same script_id and enqueues a new build. The public path keeps working on the previous succeeded artifact until the new build succeeds. The agent runs edge_function_update.
Deleting fails while any compiled endpoint still names that script_id. Remove the wasm path first, then delete. The agent runs edge_function_delete.
Things that will trip you up
- The sandbox has no sockets, filesystem, environment or timers. Outbound HTTPS is host-mediated (
fetchinside a JavaScript or Python handler). At most four calls per invocation, port 443, a DNS name, no redirects, no private addresses. A proxy endpoint is still the way to reach a private upstream. Data objects useenv.documentwhen you grant access — see Read and write data objects from a function. Math.random()repeats for a given JavaScript artifact. Do not use it for tokens or ids.- Fuel, memory and time are capped. A handler that loops or waits too long fails that request; see Limits.
Next
- Function runtimes — languages, ABIs, fetch and env.document
- Read and write data objects from a function
- Serve a data object
- Proxy a backend
- Endpoints
- Limits