API and endpoints

EndpointsCopy Anchor Link

These paths are served on the web port (PORT, default 3000) by ROLE=app and all only.

Unmatched requests under /api/*, /rpc/*, /downloads/*, /install.sh, and /healthz return 404 with {"error":"not found"} and never fall back to the web UI.

Public APICopy Anchor Link

/api/v1 and /rpc are generated from the same oRPC contract in packages/contract. The OpenAPI document is at /api/v1/openapi.json, with servers set to <EDGEWEIR_PUBLIC_URL>/api/v1; "OpenAPI" in System settings links to it.

curl -fsS https://cdn-admin.example.com/api/v1/openapi.json

AuthenticationCopy Anchor Link

• Header x-api-key: <key>: an AccessKey (starts with ewk_) or a service account key (starts with ews_).
• An AccessKey acts as the operator (the only account, created by the setup wizard); its scope decides which procedures it can call, see AccessKey. A service account key can call only the procedures listed under Service accounts.
• Invalid, revoked, or missing key: 401.
• Each AccessKey allows up to 600 requests in a row; the count restarts when more than 60 seconds pass since the previous request. Beyond that the answer is 429 API_KEY_RATE_LIMITED with data.retryAfterSeconds. Use a service account key for continuous polling; service account keys are not counted.
• Procedures that need no key (security: [] in OpenAPI): GET /system/status and POST /system/setup.
• GET /me returns the caller: { user: { id, name, email, twoFactorEnabled }, serviceAccount }; with an AccessKey, serviceAccount is null.

AccessKeyCopy Anchor Link

Managed in Personal settings → Access keys (user menu), or through accessKeys.* on /rpc with a signed-in session.

Keys without a scope count as read and write. Creation and revocation are written to the audit log (api_key.create, api_key.revoke); actions performed with an AccessKey appear in the audit log with actor type api_key. better-auth's /api/auth/api-key/* endpoints are closed and return 404.

Service accountsCopy Anchor Link

A service account is a machine identity for integrations calling /api/v1. It cannot sign in: it has no password, passkey or session, only keys. Service accounts are managed in System settings → Service accounts.

These changes are written to the audit log (service_account.create, service_account.update, service_account.delete, service_account.key_create, service_account.key_revoke); actions of a service account appear with actor type service_account. Service account keys work on /api/v1 only.

A service account can call only the procedures below, each with its scope:

For a service account, GET /me returns serviceAccount: { id, name, scopes }; user carries the service account's id and name (empty email, twoFactorEnabled false). Scopes apply to service accounts only; AccessKeys use the read-only / read-and-write scopes.

Idempotency keysCopy Anchor Link

POST, PUT and PATCH on /api/v1 accept the Idempotency-Key header: 1–255 printable ASCII characters, as an RFC 8941 string ("key") or bare.

• Keys are per caller: all AccessKeys share one set, each service account has its own.
• Records are kept 24 hours; expired ones are deleted hourly.
• 5xx responses are not kept, so the caller can retry with the same key; neither are 401 and 429 (the procedure did not run). 4xx responses are kept and replayed.
• A record still running after 10 minutes counts as interrupted (a crashed console instance); the next request takes it over and runs again.
• GET and DELETE ignore the header.

Optimistic concurrencyCopy Anchor Link

These writes accept an optional expectedUpdatedAt (ISO 8601, the updatedAt the caller read). A different value returns 409 UPDATED_AT_MISMATCH with the current value in data.updatedAt.

When a site or L4 app is already enabled or disabled as requested, sites.setEnabled and l4Apps.setEnabled return the current state without comparing expectedUpdatedAt.

Enabling and disabling sitesCopy Anchor Link

PUT /sites/{id}/enabled (procedure sites.setEnabled) with the body {"enabled":false}. The operator (session or read-and-write AccessKey) and sites:write service accounts can call it.

• A disabled site is not shipped to nodes; nodes answer HTTP requests for its domains with 503 (X-Edgeweir-Error: site-disabled) and fail the TLS handshake of HTTPS requests; its DNS records stay; certificate renewal continues and HTTP-01 challenges are answered.
• A change publishes a configuration revision (reason codes site_enabled, site_disabled) and writes an audit entry (site.enable, site.disable); an unchanged state returns the current state without a revision or audit entry.
• Purging or prefetching a disabled site: 409 SITE_DISABLED.
• The response is { site, revision }; site.enabled holds the current state.

Site delivery and launch checkCopy Anchor Link

Sites (sites.list, sites.get and the site that writes return) carry delivery:

name may be left out when creating a site (POST /sites); it defaults to the first domain (cut at 100 characters).

GET /sites/{id}/launch (procedure sites.launch) resolves each of the site's domains when called, which can take seconds:

Node capabilitiesCopy Anchor Link

When a change makes the configuration need a capability that an active node of the cluster lacks (nodes report theirs in supportedFeatures, e.g. challenge-v1, modsecurity-v1):

Automatic console jobs that publish configurations are held to the same rule as service accounts. Upgrading nodes: Node upgrades.

BansCopy Anchor Link

Service accounts cannot call these procedures (403 SERVICE_ACCOUNT_FORBIDDEN); read-only AccessKeys call GET only. scope: site covers one site, platform covers every site (shown as "Global" in the UI).

Lists answer { items, total } with active bans only (neither expired nor lifted), newest first. Ban fields:

• When an active manual ban of the same scope, site and address exists, create sets the new reason and expiry and returns the same id (audit ban.update); otherwise the audit entry is ban.create. delete lifts any active ban, manual or automatic, and writes ban.delete.
• maxTotal caps the active manual bans, site and global bans together; a renewal does not count as a new ban. shareAutoBans decides whether automatic bans reach the other nodes of the cluster. setBans is audited as system.bans_update.
• A node's ban state: banStatus of GET /nodes/{id} (appliedSequence, entries, capacity, unappliedIds, unapplied, kernelEntries, autoEvicted, reportedAt), null when the node reports none; capabilities are in supportedFeatures (bans-v1, kernel-ban-v1).

curl -fsS -X POST -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"scope":"platform","cidr":"203.0.113.0/24","reason":"attack","durationSeconds":86400}' \
  https://cdn-admin.example.com/api/v1/bans

Behavior: Bans.

Challenges and CC mitigationCopy Anchor Link

Service accounts cannot call these procedures (403 SERVICE_ACCOUNT_FORBIDDEN); read-only AccessKeys call GET only. Challenge types and CC levels: cookie302, js, pow, captcha (levels also normal).

Responses:

• A change publishes the site's cluster (reason site_protection_updated) and is audited as site.protection_update; a change of global Under Attack publishes every cluster (platform_protection_updated), audited as system.protection_update; a template change publishes clusters with sites that follow it (cc_template_updated), audited as system.cc_template_update. The daily key rotation publishes challenge_keys_rotated.
• Challenges, Under Attack, and CC need the node capability challenge-v1; logJa4 also needs ja4-v1. When an active node of the cluster lacks one, see Node capabilities.

curl -fsS -X PATCH -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"underAttack":true,"underAttackChallenge":"pow","cc":{"enabled":true,"followTemplate":true}}' \
  https://cdn-admin.example.com/api/v1/sites/<site ID>/protection

Behavior: Challenges and CC mitigation.

Compression and OWASP CRSCopy Anchor Link

Service accounts cannot call these procedures (403 SERVICE_ACCOUNT_FORBIDDEN); read-only AccessKeys can call GET only.

Responses:

• https.update publishes the site's cluster (reason certificate_updated), audited as site.https_update; waf.update publishes (site_waf_updated), audited as site.waf_update.
• bindSiteId of POST /certificates/request: once issued, the certificate is bound to that site (forceHttps and the other settings unchanged), the site's cluster is published, audited as site.https_update (actor system); names must cover every domain of the site (400 CERTIFICATE_DOMAIN_MISMATCH), and a site has at most one such request at a time (409 CERTIFICATE_BUSY). A certificate's bindSiteId is the site's ID until it is issued, then null.
• A feature with available false can still be turned on through the API; see Node capabilities.
• Unknown site: 404 SITE_NOT_FOUND.

curl -fsS -X PATCH -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"mode":"block","paranoiaLevel":1,"excludedRuleIds":[920350]}' \
  https://cdn-admin.example.com/api/v1/sites/<site ID>/waf
curl -fsS -H "x-api-key: $EDGEWEIR_API_KEY" \
  'https://cdn-admin.example.com/api/v1/sites/<site ID>/waf/rules?range=1h'

Behavior: HTTPS and certificates and OWASP CRS managed rules.

Purge, prefetch, origins and error pagesCopy Anchor Link

Service accounts cannot call these procedures (403 SERVICE_ACCOUNT_FORBIDDEN); read-only AccessKeys can call only GET.

Responses:

• errorPages.update publishes the site's cluster (reason site_error_pages_updated) and is audited as site.error_pages_update; settings.setErrorPages publishes every cluster (error_pages_updated) and is audited as system.error_pages_update.

curl -fsS -X POST -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"type":"tag","siteIds":["<site ID>"],"tags":["product-42"]}' \
  https://cdn-admin.example.com/api/v1/cache-tasks
curl -fsS -X POST -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"type":"sitemap","urls":["https://www.example.com/sitemap.xml"],"maxUrls":2000,"variants":["desktop","mobile"]}' \
  https://cdn-admin.example.com/api/v1/cache-tasks

Behavior: Origins and cache and Error pages.

Cache zone, PURGE method, content settings and maintenanceCopy Anchor Link

Service accounts cannot call these procedures (403 SERVICE_ACCOUNT_FORBIDDEN); read-only AccessKeys can call only GET.

Responses:

Configurations that use the new fields need the node capability site-content-v1 (a node's own cache size needs cache-zone-v1), see Node capabilities. Behavior: Origins and cache and Error pages.

Rules and bulk redirectsCopy Anchor Link

Service accounts cannot call these procedures (403 SERVICE_ACCOUNT_FORBIDDEN); read-only AccessKeys can call only GET and POST /rules/validate.

Responses:

• rules.save publishes the site's cluster (reason rules_updated) and is audited as site.rules_update; platformRules.save publishes every cluster and is audited as platform.rules_update; bulkRedirects.save publishes the site's cluster (rules_updated) and is audited as site.bulk_redirects_update (with the entry count).
• Configurations that use functions, the new fields, value expressions, query parameter edits, origin or compression actions, the new config phase fields, gzip: true, cache rule conditions not in the builder's shape, browserTtlSeconds, bulk redirects, or origin groups other than the default need the node capability rules-v2.
• Configurations that use the rules-v3 fields (http.request.cookies[…], http.request.uri.args[…], http.referer, http.user_agent, http.request.version, http.request.scheme, http.request.id, http.request.timestamp.sec, edge.server_port, ip.geoip.as_name, http.response.cache_status), functions (url_encode, base64_encode, base64_decode, md5, sha1, sha256, substring, to_string), wildcard / strict wildcard, an expression of a header or query parameter, append, statusCode: 303, or error page templates with {{time}} or {{path}} need the node capability rules-v3. Bulk redirects keep the statuses 301, 302, 307, and 308.
• The code of rules.validate adds cookie_name, argument_name, and integer_argument (params min and max).

curl -fsS -X PUT -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"redirects":[{"source":"/old","target":"/new","statusCode":301,"preserveQuery":true}]}' \
  https://cdn-admin.example.com/api/v1/sites/<site ID>/bulk-redirects
curl -fsS -X POST -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"expression":"regex_replace(http.request.uri.path, \"^/old/\", \"/new/\")","phase":"redirect","kind":"value"}' \
  https://cdn-admin.example.com/api/v1/rules/validate

Behavior: Rules, IP lists, and GeoIP and Origins and cache.

UsageCopy Anchor Link

One record per site and UTC 5-minute window [windowStart, windowEnd), summing the minute statistics every node reported for the window.

Record fields:

• usage.list is ordered by (window, site) and returns { items, nextCursor, completeUntil }; nextCursor null means the last page. Unaligned from / to, or to not after from: 400 USAGE_RANGE_INVALID; an invalid cursor: 400 USAGE_CURSOR_INVALID.
• usage.changes returns records created or revised after afterSeq, in seq order, as { items, lastSeq, completeUntil }; pass lastSeq as the next afterSeq. Revised records appear again.
• Windows without traffic have no record.
• Closed windows are recomputed every minute; late data that changes a value increments revision and assigns a new seq; otherwise neither changes. A statistics batch reported twice does not change the result.
• Kept 100 days by default, adjustable in System settings → Usage (35–400 days).

completeUntil (ISO 8601 or null): windows that end at or before it contain the data of every node that was active then.

Clusters and overviewCopy Anchor Link

Service accounts with clusters:read call clusters.list and clusters.get; they cannot call the others (403 SERVICE_ACCOUNT_FORBIDDEN). All are GET, so read-only AccessKeys call them.

Behavior: Clusters and system and Adding nodes.

Node channel URLCopy Anchor Link

Service accounts cannot call them (403 SERVICE_ACCOUNT_FORBIDDEN); read-only AccessKeys call settings.nodeChannel only. Enrolled nodes keep the URL they enrolled with; see Node channel URL and certificate.

Node upgradesCopy Anchor Link

Service accounts cannot call these procedures (403 SERVICE_ACCOUNT_FORBIDDEN); read-only AccessKeys call GET only.

Requirements, states, and node-side verification: Node upgrades.

Regional probes, scheduling addresses, and schedulingCopy Anchor Link

Service accounts cannot call these procedures (403 SERVICE_ACCOUNT_FORBIDDEN); read-only AccessKeys call GET only. POST /probe-tokens refuses an Idempotency-Key (see Idempotency keys).

New fields of DNS bindings and records:

Behavior: Regional probes and scheduling and DNS steering and alerts.

Listener ports and client IPCopy Anchor Link

Service accounts cannot call these procedures (403 SERVICE_ACCOUNT_FORBIDDEN); read-only AccessKeys only the GET ones.

A site's ports change with ports ({ http, https }) in PATCH /sites/{id}, and POST /sites takes the same optional field (omitted: 80 and 443); sites carry ports. Error codes: SITE_PORT_UNAVAILABLE, SITE_PORTS_EMPTY, SITE_HTTPS_PORT_NEEDS_CERTIFICATE. The settings of PUT /sites/{id}/https add redirectStatus (301, 302, 303, 307, 308, default 301), redirectPort (443 or an HTTPS port of the site, default 443, HTTPS_REDIRECT_PORT_INVALID) and redirectExcludedDomains (domains of the site, at most 50, HTTPS_REDIRECT_DOMAIN_INVALID). GET /sites/{id}/features adds edgePorts and clientIp; clusters of GET /clusters add clientIpMode.

Port pools and L4 appsCopy Anchor Link

Service accounts cannot call these procedures (403 SERVICE_ACCOUNT_FORBIDDEN); read-only AccessKeys call GET only.

• create and update publish the cluster's configuration revision (reasons l4_app_created, l4_app_updated) and audit l4_app.create, l4_app.update; setEnabled publishes when the state changes (l4_app_updated) and audits l4_app.enable or l4_app.disable, and returns the latest revision without publishing or auditing when it does not; delete publishes (l4_app_deleted) and audits l4_app.delete. setPortPools audits cluster.port_pools_update.
• A configuration with an enabled app needs the node capability l4-v1, see Node capabilities.

curl -fsS -X PUT -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"pools":[{"protocol":"both","from":20000,"to":20100}]}' \
  https://cdn-admin.example.com/api/v1/clusters/<cluster ID>/port-pools
curl -fsS -X POST -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"clusterId":"<cluster ID>","name":"game","protocol":"tcp","port":20000,"origins":[{"address":"game-origin.example.com","port":7000}],"proxyProtocolVersion":2}' \
  https://cdn-admin.example.com/api/v1/l4-apps

Behavior: Layer-4 forwarding.

ExampleCopy Anchor Link

List sites (procedure sites.list, GET /api/v1/sites):

curl -fsS -H "x-api-key: $EDGEWEIR_API_KEY" \
  "https://cdn-admin.example.com/api/v1/sites?page=1&pageSize=20"

Response: {"items":[…],"total":<count>}.

Error formatCopy Anchor Link

{
  "defined": false,
  "code": "ACCESS_KEY_READ_ONLY",
  "status": 403,
  "message": "access key is read only",
  "data": {}
}

Authentication and input validation failures use the generic oRPC codes UNAUTHORIZED (401) and BAD_REQUEST (400).

Web UI RPCCopy Anchor Link

/rpc/* uses the oRPC RPC protocol for the web UI; the path is the procedure path, e.g. POST /rpc/sites/list.

Third-party integrations use /api/v1.

Authentication endpointsCopy Anchor Link

better-auth handles /api/auth/*, limited to the paths and methods below. Matching is exact (no prefixes, encoded variants, or trailing slashes); every other request returns 404. x-api-key is stripped from requests; the client IP is resolved according to EDGEWEIR_TRUSTED_PROXIES before it reaches better-auth. There is no public sign-up: the setup wizard creates the only account. AccessKeys are managed through accessKeys.*. With NODE_ENV=production, rate limiting is on, with counters in PostgreSQL.

Health checkCopy Anchor Link

GET /healthz returns 200:

{ "status": "ok", "version": "20260929-a1b2c3d" }

The response comes from the listening HTTP server; the database is not checked. Container health check: Command line.

Installer and release mirrorCopy Anchor Link

GET /install.sh returns the node installer (text/x-shellscript, cache-control: no-store) with the console URL replaced by EDGEWEIR_PUBLIC_URL. Options: Command line.

GET and HEAD on /downloads/* serve files from EDGEWEIR_DOWNLOADS_DIR; the URL path equals the relative path in the directory:

<project> is edgeweir-node or cosign; the edgeweir-openresty and edgeweir-openresty-modsecurity packages go into the same version directory as edgeweir-node. Other paths, missing files, and symbolic links leading out of the directory return 404. Preparing the directory: Adding nodes.

Node channelCopy Anchor Link