Skip to content

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 default workspace. To select another one, send workspace_id as 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 ​

MethodPathReturns
GET/health{"ok": true} — platform probe, not under /v1
GET/v1/openapi.jsonOpenAPI 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 ​

MethodPathScope
GET/v1/organizations/{org_id}/workspacesnamespace.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:

json
[
  {
    "id": "0b8e4a52-31d7-4c9f-9a18-2f6c5d0b7e43",
    "organization_id": "7c1f9d84-6b20-4e3a-8f57-d94a2e1b6c08",
    "slug": "default",
    "distribution_count": 3
  }
]

Distributions ​

MethodPathScope
GET/v1/slugs/{slug}distribution.read
GET/v1/distributionsdistribution.read
POST/v1/distributionsdistribution.write
GET/v1/distributions/{id}distribution.read
PATCH/v1/distributions/{id}distribution.write
POST/v1/distributions/{id}/copydistribution.write
DELETE/v1/distributions/{id}distribution.destroy

Deployments ​

MethodPathScope
GET/v1/distributions/{id}/deploymentsdeployment.read
POST/v1/distributions/{id}/deploymentsdeployment.write
POST/v1/distributions/{id}/checkdeployment.write
GET/v1/deployments/{id}deployment.read
POST/v1/deployments/{id}/commitdeployment.write
POST/v1/deployments/{id}/promotedeployment.promote
GET/v1/deployments/{from}/diff/{to}deployment.read
POST/v1/distributions/{id}/rollbackdeployment.promote
GET/v1/distributions/{id}/schedulesdeployment.read
DELETE/v1/schedules/{id}deployment.promote
POST/v1/distributions/{id}/takedowndeployment.promote
POST/v1/distributions/{id}/restoredeployment.promote
GET/v1/deployments/{id}/contentdeployment.read
PUT/v1/deployments/{id}/contentdeployment.write
DELETE/v1/deployments/{id}/contentdeployment.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 ​

MethodPathScope
GET/v1/distributions/{id}/documentsdocument.read
PUT/v1/distributions/{id}/documentsdocument.write
DELETE/v1/distributions/{id}/documentsdocument.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 ​

MethodPathScope
GET/v1/distributions/{id}/store-grantsfunction.read
PUT/v1/distributions/{id}/store-grantsfunction.write
GET/v1/distributions/{id}/kvfunction.read
GET/v1/distributions/{id}/kv/{key:path}function.read
PUT/v1/distributions/{id}/kv/{key:path}function.write
DELETE/v1/distributions/{id}/kvfunction.write
POST/v1/distributions/{id}/sqlfunction.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 ​

MethodPathScope
GET/v1/domainsdomain.read
POST/v1/domainsdomain.manage
GET/v1/domains/{fqdn}domain.read
POST/v1/domains/{fqdn}/verifydomain.manage
POST/v1/domains/{fqdn}/attachdomain.manage
POST/v1/domains/{fqdn}/detachdomain.manage
DELETE/v1/domains/{fqdn}domain.destroy

Checks ​

MethodPathScope
POST/v1/distributions/{id}/invalidatedeployment.promote
GET/v1/distributions/{id}/redirect-checkdistribution.read
POST/v1/distributions/{id}/redirects/importdistribution.write
GET/v1/distributions/{id}/redirects/exportdistribution.read
GET/v1/distributions/{id}/header-checkdistribution.read
GET/v1/distributions/{id}/healthanalytics.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 ​

MethodPathScope
POST/v1/analyticsanalytics.read
POST/v1/analytics/exploreanalytics.read
GET/v1/analytics/realtimeanalytics.read
GET/v1/logslogs.read
GET/v1/logs/{id}logs.read

Goals ​

MethodPathScope
POST/v1/distributions/{id}/goals/checkgoals.read
GET/v1/distributions/{id}/goalsgoals.read
GET/v1/distributions/{id}/goals/{goal_id}goals.read
POST/v1/distributions/{id}/goalsgoals.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}/archivegoals.write

Analytics groups and funnels ​

MethodPathScope
GET/v1/groupsfunnels.read
GET/v1/groups/{group_id}funnels.read
POST/v1/groupsfunnels.write
PATCH/v1/groups/{group_id}funnels.write
POST/v1/groups/{group_id}/funnels/checkfunnels.read
GET/v1/groups/{group_id}/funnelsfunnels.read
GET/v1/groups/{group_id}/funnels/{funnel_id}funnels.read
POST/v1/groups/{group_id}/funnelsfunnels.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}/archivefunnels.write
POST/v1/groups/{group_id}/funnels/{funnel_id}/queryfunnels.read

Properties and PII ​

MethodPathScope
GET/v1/distributions/{id}/properties/checkanalytics.read
GET/v1/distributions/{id}/propertiesanalytics.read
POST/v1/distributions/{id}/properties/{key}/declareproperties.write
PATCH/v1/distributions/{id}/properties/{key}properties.write
DELETE/v1/distributions/{id}/properties/{key}properties.write
GET/v1/distributions/{id}/pii-policypii.read
PUT/v1/distributions/{id}/pii-policypii.policy.write
POST/v1/distributions/{id}/pii-exemptionspii.policy.write
DELETE/v1/distributions/{id}/pii-exemptionspii.policy.write
GET/v1/pii-detectorspii.read
GET/v1/distributions/{id}/pii-reportpii.read

See Declare an analytics property and Protect analytics properties for the lifecycle and policy rules behind these routes.

Webhooks and hooks ​

MethodPathScope
GET/v1/webhookswebhook.read
POST/v1/webhookswebhook.write
GET/v1/webhooks/{id}webhook.read
PATCH/v1/webhooks/{id}webhook.write
DELETE/v1/webhooks/{id}webhook.write
POST/v1/webhooks/{id}/testwebhook.write
POST/v1/webhooks/{id}/rotate-secretwebhook.write
GET/v1/webhooks/{id}/deliverieswebhook.read
POST/v1/webhooks/{id}/deliveries/{delivery_id}/redeliverwebhook.write
GET/v1/distributions/{id}/hookshook.read
POST/v1/distributions/{id}/hookshook.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}/receiptshook.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.

MethodPathScope
GET/v1/distributions/{id}/jobsfunction.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 ​

MethodPathScope
GET/v1/distributions/{id}/cronscron.read
POST/v1/distributions/{id}/cronscron.write
POST/v1/distributions/{id}/crons/checkcron.read
GET/v1/crons/{id}cron.read
PATCH/v1/crons/{id}cron.write
DELETE/v1/crons/{id}cron.write
POST/v1/crons/{id}/triggercron.write
GET/v1/crons/{id}/runscron.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 ​

MethodPathScope
GET/v1/distributions/{id}/queuesqueue.read
POST/v1/distributions/{id}/queuesqueue.write
GET/v1/queues/{id}queue.read
PATCH/v1/queues/{id}queue.write
DELETE/v1/queues/{id}queue.write
POST/v1/queues/{id}/messagesqueue.send
GET/v1/queues/{id}/messagesqueue.read
POST/v1/queues/{id}/purgequeue.write
POST/v1/queues/{id}/redrivequeue.write
GET/v1/queues/{id}/statsqueue.read
GET/v1/queues/{id}/runsqueue.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 ​

MethodPathScope
GET/v1/distributions/{id}/workflowsworkflow.read
POST/v1/distributions/{id}/workflowsworkflow.write
GET/v1/workflows/{id}workflow.read
POST/v1/workflows/{id}/signalsworkflow.write
POST/v1/workflows/{id}/cancelworkflow.write
POST/v1/workflows/{id}/retryworkflow.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 ​

MethodPathScope
GET/v1/distributions/{id}/submissionssubmission.read
GET/v1/distributions/{id}/submissions/access-logsubmission.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}/downloadsubmission.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 ​

MethodPathScope
GET/v1/distributions/{id}/access/rulesaccess.read
POST/v1/distributions/{id}/access/rulesaccess.write
DELETE/v1/access/rules/{id}access.write
POST/v1/distributions/{id}/access/checkaccess.read
GET/v1/distributions/{id}/access/revocationsaccess.read
POST/v1/distributions/{id}/access/sessions/revokeaccess.write
GET/v1/distributions/{id}/access/network-rulesaccess.read
POST/v1/distributions/{id}/access/network-rulesaccess.write
GET/v1/access/network-rulesaccess.read
POST/v1/access/network-rulesaccess.write
DELETE/v1/access/network-rules/{id}access.write
POST/v1/distributions/{id}/access/network-checkaccess.read
PUT/v1/distributions/{id}/access/network-modeaccess.write

The password gate itself is PATCH /v1/distributions/{id} with access. See Access control.

Personal access tokens ​

MethodPathScope
GET/v1/tokenssigned in; ?all=true needs token.admin
POST/v1/tokenssigned 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.

See also ​