HTTP API
Base URL: https://api.edge.deca-dev.com. All routes below are prefixed /v1 and require a bearer token for the https://api.edge.deca-dev.com audience. Use that host for the whole workflow. See Environments and domains.
Matching MCP tools call the same handler with the same permission check. Tools that have no HTTP route — function runtimes, document history and grants, private data objects, feedback — are listed only on the MCP page.
Path segments containing slashes or dots — a content or document path, a domain name — are URL-encoded.
Conventions
- Organization comes from the token and is never passed as a parameter. In
/v1/organizations/{org_id}/workspaces,{org_id}must equal the token's organization or the request returns 403; the path does not select a different one. - Workspace is optional for most routes. Omitted, Edge uses your organization's
defaultworkspace. To select another one, sendworkspace_idas a query parameter or JSON field. The log stream requires it explicitly. - These are console aliases for the system tenant and namespace. See Organizations and workspaces.
- Authenticated responses are
Cache-Control: no-store. - Lists that paginate use a cursor.
Unauthenticated routes
| Method | Path | Returns |
|---|---|---|
GET | /health | {"ok": true} — platform probe, not under /v1 |
GET | /v1/openapi.json | OpenAPI description of every route below. It does not describe MCP. |
GET | /v1/file-links/{token} | A webhook's download_url for one submitted file: 302 to a 60-second download once the file is clean, 409 before. See Form submissions. |
Routes
Workspaces
| Method | Path | Scope |
|---|---|---|
GET | /v1/organizations/{org_id}/workspaces | namespace.read |
There is no MCP list equivalent. edge_namespace_get returns the single workspace bound to the token. See MCP.
Workspace records are returned as an array of:
[
{
"id": "0b8e4a52-31d7-4c9f-9a18-2f6c5d0b7e43",
"organization_id": "7c1f9d84-6b20-4e3a-8f57-d94a2e1b6c08",
"slug": "default",
"distribution_count": 3
}
]Distributions
| Method | Path | Scope |
|---|---|---|
GET | /v1/slugs/{slug} | distribution.read |
GET | /v1/distributions | distribution.read |
POST | /v1/distributions | distribution.write |
GET | /v1/distributions/{id} | distribution.read |
PATCH | /v1/distributions/{id} | distribution.write |
POST | /v1/distributions/{id}/copy | distribution.write |
DELETE | /v1/distributions/{id} | distribution.destroy |
Deployments
| Method | Path | Scope |
|---|---|---|
GET | /v1/distributions/{id}/deployments | deployment.read |
POST | /v1/distributions/{id}/deployments | deployment.write |
POST | /v1/distributions/{id}/check | deployment.write |
GET | /v1/deployments/{id} | deployment.read |
POST | /v1/deployments/{id}/commit | deployment.write |
POST | /v1/deployments/{id}/promote | deployment.promote |
GET | /v1/deployments/{from}/diff/{to} | deployment.read |
POST | /v1/distributions/{id}/rollback | deployment.promote |
GET | /v1/distributions/{id}/schedules | deployment.read |
DELETE | /v1/schedules/{id} | deployment.promote |
POST | /v1/distributions/{id}/takedown | deployment.promote |
POST | /v1/distributions/{id}/restore | deployment.promote |
GET | /v1/deployments/{id}/content | deployment.read |
PUT | /v1/deployments/{id}/content | deployment.write |
DELETE | /v1/deployments/{id}/content | deployment.write |
GET | /v1/deployments/{id}/content/{path:path} | deployment.read |
promote, takedown and restore take an optional at (ISO 8601 with a timezone offset). With at, the call creates a schedule and returns schedule_id instead of acting now. takedown takes mode (gone or redirect) and, for redirect, location. schedules takes status (scheduled by default, or running, done, cancelled, failed, all). See Schedule a launch and a takedown.
Data objects
| Method | Path | Scope |
|---|---|---|
GET | /v1/distributions/{id}/documents | document.read |
PUT | /v1/distributions/{id}/documents | document.write |
DELETE | /v1/distributions/{id}/documents | document.write |
GET | /v1/distributions/{id}/documents/{path:path} | document.read |
The write body field is objects. Version history, rollback, function grants, and the private data-object store are MCP-only — see MCP and Serve a data object.
Key-value and SQL
| Method | Path | Scope |
|---|---|---|
GET | /v1/distributions/{id}/store-grants | function.read |
PUT | /v1/distributions/{id}/store-grants | function.write |
GET | /v1/distributions/{id}/kv | function.read |
GET | /v1/distributions/{id}/kv/{key:path} | function.read |
PUT | /v1/distributions/{id}/kv/{key:path} | function.write |
DELETE | /v1/distributions/{id}/kv | function.write |
POST | /v1/distributions/{id}/sql | function.read |
PUT store-grants takes store (kv or sql), mode (none, read, or read-write), and an optional scripts list. GET kv takes prefix, cursor, and limit. PUT kv takes value, and optional ttl_seconds and if_version. DELETE kv takes keys. POST sql takes statements. A read-only statement needs function.read; a statement that writes also needs function.write. The web console does not manage these yet. See Use key-value and SQL storage from a function.
Domains
| Method | Path | Scope |
|---|---|---|
GET | /v1/domains | domain.read |
POST | /v1/domains | domain.manage |
GET | /v1/domains/{fqdn} | domain.read |
POST | /v1/domains/{fqdn}/verify | domain.manage |
POST | /v1/domains/{fqdn}/attach | domain.manage |
POST | /v1/domains/{fqdn}/detach | domain.manage |
DELETE | /v1/domains/{fqdn} | domain.destroy |
Checks
| Method | Path | Scope |
|---|---|---|
POST | /v1/distributions/{id}/invalidate | deployment.promote |
GET | /v1/distributions/{id}/redirect-check | distribution.read |
POST | /v1/distributions/{id}/redirects/import | distribution.write |
GET | /v1/distributions/{id}/redirects/export | distribution.read |
GET | /v1/distributions/{id}/header-check | distribution.read |
GET | /v1/distributions/{id}/health | analytics.read |
Redirect and header checks inspect stored config only. redirect-check takes path (a query string is allowed) and an optional deployment_id. redirects/import takes source, format (csv, netlify, json), mode (merge or replace) and dry_run (default true). redirects/export takes format and an optional deployment_id. See Redirects. A permissions-policy value must be one of the two strings in Permissions-Policy. Setting headers creates a deployment; visitors see it after that deployment is promoted.
Analytics and logs
| Method | Path | Scope |
|---|---|---|
POST | /v1/analytics | analytics.read |
POST | /v1/analytics/explore | analytics.read |
GET | /v1/analytics/realtime | analytics.read |
GET | /v1/logs | logs.read |
GET | /v1/logs/{id} | logs.read |
Goals
| Method | Path | Scope |
|---|---|---|
POST | /v1/distributions/{id}/goals/check | goals.read |
GET | /v1/distributions/{id}/goals | goals.read |
GET | /v1/distributions/{id}/goals/{goal_id} | goals.read |
POST | /v1/distributions/{id}/goals | goals.write |
PUT | /v1/distributions/{id}/goals/{slug} | goals.write |
PATCH | /v1/distributions/{id}/goals/{goal_id} | goals.write |
POST | /v1/distributions/{id}/goals/{goal_id}/archive | goals.write |
Analytics groups and funnels
| Method | Path | Scope |
|---|---|---|
GET | /v1/groups | funnels.read |
GET | /v1/groups/{group_id} | funnels.read |
POST | /v1/groups | funnels.write |
PATCH | /v1/groups/{group_id} | funnels.write |
POST | /v1/groups/{group_id}/funnels/check | funnels.read |
GET | /v1/groups/{group_id}/funnels | funnels.read |
GET | /v1/groups/{group_id}/funnels/{funnel_id} | funnels.read |
POST | /v1/groups/{group_id}/funnels | funnels.write |
PUT | /v1/groups/{group_id}/funnels/{slug} | funnels.write |
PATCH | /v1/groups/{group_id}/funnels/{funnel_id} | funnels.write |
POST | /v1/groups/{group_id}/funnels/{funnel_id}/archive | funnels.write |
POST | /v1/groups/{group_id}/funnels/{funnel_id}/query | funnels.read |
Properties and PII
| Method | Path | Scope |
|---|---|---|
GET | /v1/distributions/{id}/properties/check | analytics.read |
GET | /v1/distributions/{id}/properties | analytics.read |
POST | /v1/distributions/{id}/properties/{key}/declare | properties.write |
PATCH | /v1/distributions/{id}/properties/{key} | properties.write |
DELETE | /v1/distributions/{id}/properties/{key} | properties.write |
GET | /v1/distributions/{id}/pii-policy | pii.read |
PUT | /v1/distributions/{id}/pii-policy | pii.policy.write |
POST | /v1/distributions/{id}/pii-exemptions | pii.policy.write |
DELETE | /v1/distributions/{id}/pii-exemptions | pii.policy.write |
GET | /v1/pii-detectors | pii.read |
GET | /v1/distributions/{id}/pii-report | pii.read |
See Declare an analytics property and Protect analytics properties for the lifecycle and policy rules behind these routes.
Webhooks and hooks
| Method | Path | Scope |
|---|---|---|
GET | /v1/webhooks | webhook.read |
POST | /v1/webhooks | webhook.write |
GET | /v1/webhooks/{id} | webhook.read |
PATCH | /v1/webhooks/{id} | webhook.write |
DELETE | /v1/webhooks/{id} | webhook.write |
POST | /v1/webhooks/{id}/test | webhook.write |
POST | /v1/webhooks/{id}/rotate-secret | webhook.write |
GET | /v1/webhooks/{id}/deliveries | webhook.read |
POST | /v1/webhooks/{id}/deliveries/{delivery_id}/redeliver | webhook.write |
GET | /v1/distributions/{id}/hooks | hook.read |
POST | /v1/distributions/{id}/hooks | hook.write |
GET | /v1/distributions/{id}/hooks/{hook_id} | hook.read |
PATCH | /v1/distributions/{id}/hooks/{hook_id} | hook.write |
DELETE | /v1/distributions/{id}/hooks/{hook_id} | hook.write |
GET | /v1/distributions/{id}/hooks/{hook_id}/receipts | hook.read |
GET | /v1/distributions/{id}/hooks/{hook_id}/receipts/{key} | hook.read |
Creating or widening a subscription to form.* also needs form.forward and "confirm": true. The public /_hooks/{hook} URL on a distribution host takes no bearer token. See Events, webhooks, and hooks.
Endpoints
The /_api map lives on the distribution as runtime.api.routes. See Endpoints for data objects, backend proxies and function runtimes.
Function runtimes are MCP-only (edge_function_*). Mapping a handler onto /_api is a distribution update (PATCH /v1/distributions/{id}) with a wasm route. There are no /v1/functions routes. See MCP and Add an endpoint.
| Method | Path | Scope |
|---|---|---|
GET | /v1/distributions/{id}/jobs | function.read |
jobs lists background job runs newest first. Query parameters: owner_kind (cron, queue, workflow, test), owner_id, status, before (the previous page's next_before) and limit (default 50, max 100).
Crons
| Method | Path | Scope |
|---|---|---|
GET | /v1/distributions/{id}/crons | cron.read |
POST | /v1/distributions/{id}/crons | cron.write |
POST | /v1/distributions/{id}/crons/check | cron.read |
GET | /v1/crons/{id} | cron.read |
PATCH | /v1/crons/{id} | cron.write |
DELETE | /v1/crons/{id} | cron.write |
POST | /v1/crons/{id}/trigger | cron.write |
GET | /v1/crons/{id}/runs | cron.read |
POST …/crons takes name, schedule, target, and optional timezone (IANA, default UTC), overlap (skip or allow), retries (0–3) and enabled. PATCH takes any of those. check takes schedule, timezone and target and writes nothing. trigger runs the cron once now without moving its next run. runs takes status, before and limit. See Cron syntax.
Queues
| Method | Path | Scope |
|---|---|---|
GET | /v1/distributions/{id}/queues | queue.read |
POST | /v1/distributions/{id}/queues | queue.write |
GET | /v1/queues/{id} | queue.read |
PATCH | /v1/queues/{id} | queue.write |
DELETE | /v1/queues/{id} | queue.write |
POST | /v1/queues/{id}/messages | queue.send |
GET | /v1/queues/{id}/messages | queue.read |
POST | /v1/queues/{id}/purge | queue.write |
POST | /v1/queues/{id}/redrive | queue.write |
GET | /v1/queues/{id}/stats | queue.read |
GET | /v1/queues/{id}/runs | queue.read |
POST …/queues takes name, consumer ({"type": "wasm", "script_id"} or {"type": "webhook", "url"}), and optional batch_size, batch_wait_seconds, concurrency, max_attempts, retention_days, paused and senders. A webhook consumer's answer includes signing_secret once. PATCH takes any of those. POST …/messages takes messages: 1–100 of {"body", "delay_seconds"?, "idempotency_key"?}. GET …/messages takes status (ready, leased or dead), include_bodies=true, before and limit. purge takes status (ready or dead) and confirm: true. redrive takes optional message_ids. A refused send keeps its code: queue_full and rate_limited are 429, too_large is 413. See Process work in the background with a queue.
Workflows
| Method | Path | Scope |
|---|---|---|
GET | /v1/distributions/{id}/workflows | workflow.read |
POST | /v1/distributions/{id}/workflows | workflow.write |
GET | /v1/workflows/{id} | workflow.read |
POST | /v1/workflows/{id}/signals | workflow.write |
POST | /v1/workflows/{id}/cancel | workflow.write |
POST | /v1/workflows/{id}/retry | workflow.write |
POST …/workflows takes script_id and optional input, name, idempotency_key and retries (0–5). GET …/workflows takes status, before and limit. signals takes name and optional payload and idempotency_key. A signal to a finished run is 409run_finished; a start past the active-run cap is 429 limit_reached. See Build a multi-step workflow.
Form submissions
| Method | Path | Scope |
|---|---|---|
GET | /v1/distributions/{id}/submissions | submission.read |
GET | /v1/distributions/{id}/submissions/access-log | submission.read |
GET | /v1/distributions/{id}/submissions/{sid} | submission.read |
GET | /v1/distributions/{id}/submissions/{sid}/files/{upload_id} | submission.read |
GET | /v1/distributions/{id}/submissions/{sid}/files/{upload_id}/download | submission.read |
The list takes form_id, since (default 30 days ago) and cursor; the access log takes since; one submission takes an optional form_id. A file read takes output (text, the default, link or content) and, for text, offset. download answers 302 to a 60-second download. Only files whose scan is clean can be read. Reads with a personal access token are capped per day and see the distribution's submission PII policy; a person's own sign-in sees raw values. A form's upload policy is runtime.uploads on PATCH /v1/distributions/{id}. See Let an agent read form submissions.
Access
| Method | Path | Scope |
|---|---|---|
GET | /v1/distributions/{id}/access/rules | access.read |
POST | /v1/distributions/{id}/access/rules | access.write |
DELETE | /v1/access/rules/{id} | access.write |
POST | /v1/distributions/{id}/access/check | access.read |
GET | /v1/distributions/{id}/access/revocations | access.read |
POST | /v1/distributions/{id}/access/sessions/revoke | access.write |
GET | /v1/distributions/{id}/access/network-rules | access.read |
POST | /v1/distributions/{id}/access/network-rules | access.write |
GET | /v1/access/network-rules | access.read |
POST | /v1/access/network-rules | access.write |
DELETE | /v1/access/network-rules/{id} | access.write |
POST | /v1/distributions/{id}/access/network-check | access.read |
PUT | /v1/distributions/{id}/access/network-mode | access.write |
The password gate itself is PATCH /v1/distributions/{id} with access. See Access control.
Personal access tokens
| Method | Path | Scope |
|---|---|---|
GET | /v1/tokens | signed in; ?all=true needs token.admin |
POST | /v1/tokens | signed in, not with a personal access token |
DELETE | /v1/tokens/{id} | signed in; another person's token needs token.admin |
POST /v1/tokens creates nothing unless the body has "confirm": true. Without it, the response is the summary to show the person. See Create a personal access token.
Notes on specific routes
DELETE routes that remove something live require a confirmation field in the body — slug for a distribution, confirm_fqdn for a domain. A mismatch returns 422.
POST /v1/analytics/stream exists but is not in the table above: it is a server-sent event stream rather than a request/response route, and has no MCP tool. It requires analytics.read.
GET /v1/logs/stream is also a server-sent event stream with no MCP equivalent. It requires logs.read plus explicit workspace_id and distribution_id query parameters. The stream closes after a bounded number of poll cycles; reconnecting is normal.