Skip to main content

Account API

Public health check

GET https://api.edgedns.dev/health needs no authentication and returns status and timestamp. Healthy or degraded service returns HTTP 200; unhealthy returns 503. Use this for service readiness, not as a domain analysis endpoint.

Use https://api.edgedns.dev and an EdgeDNS API-key Bearer header for the routes below. Nonempty permission lists use route namespaces: keys:read, keys:write, billing:read, analytics:read, history:read, or alerts:read/alerts:write. Plan, subscription, and organization checks still apply. See authentication.

These account and monitoring operations supplement the analysis endpoint catalog. Most account responses use { "success": true, "data": { ... } }; they do not all include the analysis API’s meta object. Check HTTP status and error.code instead of assuming one success envelope for every route.

API keys

EndpointRequest and response
GET /v1/keysReturns data.keys with id, name, prefix, hint, environment, last_used_at, created_at, and settings. Full secrets are not included.
POST /v1/keysJSON: required name (1–100 characters); optional environment (live/test, default live), ip_allowlist (string array), expires_at (ISO 8601 datetime with timezone or null). Returns HTTP 201, data.key and metadata, plus a storage warning. Store the full key at creation.
GET /v1/keys/:idRead key details and settings; includes revoked_at.
PUT /v1/keys/:idJSON: any of name, ip_allowlist, expires_at. Returns updated details. Does not accept permissions or environment changes.
DELETE /v1/keys/:idRevoke a key. Revocation prevents future use.

Keys use edns_live_ or edns_test_ prefixes. The test prefix is a key label; it does not create a separate billing sandbox or remove usage charges. Key-count limits depend on your plan. REST creation does not accept a description or permissions field.

Billing and effective usage

EndpointRequest and response
GET /v1/billing/subscriptionReturns data.tier, status, current_period_end, cancel_at_period_end.
GET /v1/billing/usageCurrent UTC calendar-month usage and effective quota. Returns data.period, usage (total_requests and by_endpoint), quota (limit, used, percent, remaining), and tier. Usage is an eventually updated projection; it can lag enforcement. A period query parameter does not select another period on this route.
GET /v1/billing/historylimit defaults to 10, maximum 100. Returns data.invoices with id, amount_cents, status, date, invoice_pdf.
GET /v1/billing/portalRequired return_url query parameter (URL). Creates a billing portal session and returns data.portal_url. Requires an existing billing account.

New subscription checkout and plan changes require a signed-in dashboard session. An API key cannot call the Clerk-authenticated checkout routes. Use dashboard billing to manage your subscription.

Request analytics and query history

EndpointRequest and response
GET /v1/analytics/usageAccepts period=current (default), 7d, or 30d, but the counters currently always cover the current UTC month; the returned period label can describe a different range. Returns period, total_requests, by_endpoint, and quota inside data. The quota here is the default plan allowance; use billing/usage for the effective quota including overrides.
GET /v1/analytics/usage/by-endpointAccepts the same period values, but currently returns current UTC-month counters regardless. Returns data.endpoints sorted by request count.
GET /v1/analytics/usage/by-keyCurrent-month key usage. Returns data.keys sorted by requests; no period selector.
GET /v1/analytics/performanceperiod=current, 7d, or 30d. Returns latency statistics and breakdowns from logged requests.
GET /v1/analytics/cacheSame period values. Returns cache-hit summary, endpoint breakdown, and daily timeseries.
GET /v1/analytics/errorsSame period values. Returns error summary and breakdowns from logged requests.
GET /v1/history/queriesFilters: endpoint, target, api_key_id, status_code, cache_hit (true/false), error_code, from, to. limit defaults to 100 (maximum 1,000), offset defaults to 0. Returns data.queries, data.pagination, data.retention.
GET /v1/history/queries/:idReturns data.query with parameters, response summary, request_id, timing, status, and other logged metadata.
GET /v1/history/statsOptional from and to filters. Returns aggregate query history statistics.
GET /v1/pingAuthenticated connectivity check; returns message, timestamp, and org directly.

For /v1/history and /v1/alerts/history date filters, send ISO 8601 datetime strings with a timezone, such as 2026-11-01T00:00:00Z. Stored numeric timestamps are Unix milliseconds. Portal usage date filters accept Unix milliseconds. Query history is private to your organization and has tier-dependent retention (Free 30 days, Developer 90 days, Pro and Enterprise 365 days). Logged analytics are reporting data and can lag new requests. Query history records API requests; domain monitoring snapshots are documented under the Monitoring API.

Organization alert rules and history

EndpointRequest and response
GET /v1/alerts/rulesOptional enabled=true/false and alert_type. Returns organization alert rules.
POST /v1/alerts/rulesCreate an alert rule using the fields below.
GET /v1/alerts/rules/:idRead one rule.
PUT /v1/alerts/rules/:idUpdate enabled, threshold_value, threshold_window_minutes, channels, cooldown_minutes. alert_type is immutable.
DELETE /v1/alerts/rules/:idDelete one rule.
GET /v1/alerts/historyOptional status (pending/acknowledged/resolved), alert_type, rule_id, from, to. limit defaults to 100 (maximum 1,000); offset defaults to 0.
GET /v1/alerts/history/:idRead one historical alert.
POST /v1/alerts/history/:id/acknowledgeAcknowledge an alert; optional JSON notes string.
POST /v1/alerts/history/:id/resolveResolve an alert; optional JSON notes string.

Create a rule with required alert_type; optional enabled (default true), threshold_value (number), threshold_window_minutes (positive integer), channels (array containing email; default [email]), and cooldown_minutes (positive integer, default 60). Supported alert_type values: error_rate_spike, latency_spike, external_api_down, circuit_breaker_open, degradation_active, rate_limit_hit, anomaly_detected, ssl_expiry, domain_expiry, dns_changed, security_score_drop, new_subdomain.

These rule and history routes manage organization alerts; creating a rule does not create a domain watch or schedule an endpoint check. For endpoint snapshots and change notifications, configure a watch through the Monitoring API.

Dashboard session API

The dashboard uses /v1/portal/* with a Clerk session JWT in the Authorization Bearer header. EdgeDNS API keys and MCP OAuth tokens cannot authenticate these routes. Organization role and permission checks apply to sensitive actions. These are dashboard integration routes; use the API-key routes above for server integrations.

EndpointRequest and response
GET /v1/portal/pingCheck signed-in portal connectivity.
GET /v1/portal/keys; POST /v1/portal/keysList keys or create a key (name, optional environment, ip_allowlist, expires_at).
GET /v1/portal/keys/:id/revealReveal an encrypted key belonging to the organization.
POST /v1/portal/keys/ensure-defaultProvision or return the managed default key.
POST /v1/portal/keys/:id/regenerate; POST /v1/portal/keys/regenerate-allRotate keys. Bulk rotation requires {"confirm":"regenerate all keys"}. Existing secrets stop working.
DELETE /v1/portal/keys/:idRevoke a dashboard-managed key.
GET /v1/portal/usage; GET /v1/portal/usage/historyUsage reporting and request ledger; history accepts limit, offset, from, to, api_key_id, endpoint.
GET /v1/portal/billingSubscription details and billing status for the dashboard.
POST /v1/portal/billing/portalCreate a Stripe customer portal session; returns data.url.
POST /v1/portal/billing/checkout; POST /v1/portal/billing/upgrade-checkoutJSON: tier (developer/pro), success_url, cancel_url. Initiates a new paid subscription or upgrade checkout.
GET /v1/portal/billing/checkout-previewRequired tier=developer/pro. Returns an approximate signup price preview.
POST /v1/portal/billing/proration-preview; POST /v1/portal/billing/change-planJSON: tier (free/developer/pro). Preview or initiate a plan change, subject to subscription state.
POST /v1/portal/billing/cancel-downgradeCancel a scheduled downgrade.
POST /v1/portal/billing/verify-checkoutJSON: session_id (cs_ prefix). Verify and fulfill the organization’s completed checkout.
GET/POST /v1/portal/watches and watch subroutesDashboard equivalents of the Monitoring API, with role-based writes. Also PATCH /:id/pause and PATCH /:id/resume.
GET /v1/portal/notifications; GET /v1/portal/notifications/unread-countList notifications or read the unread count.
PATCH /v1/portal/notifications/:id/read; POST /v1/portal/notifications/mark-all-readMark one notification or all notifications read.
GET/PATCH/DELETE /v1/portal/profileRead profile or PATCH name and billing_address. DELETE schedules organization deletion; owner-only JSON confirmation must equal the organization name.
GET /v1/portal/members; POST /v1/portal/members/inviteList members/invitations or invite a member with email and role.
POST /v1/portal/members/invitations/:token/acceptAccept an invitation as the authenticated invited user.
PUT /v1/portal/members/:memberId/role; PUT /v1/portal/members/:memberId/permissionsUpdate role or permissions under organization authorization.
DELETE /v1/portal/members/:memberId; DELETE /v1/portal/members/invitations/:invitationIdRemove a member or revoke an invitation.
PUT /v1/portal/members/:memberId/transfer-ownershipOwner-only organization ownership transfer.
GET /v1/portal/oauth/consent; POST /v1/portal/oauth/consentGET requires session_id; POST accepts session_id and action (approve/deny). Read an OAuth authorization session and submit consent.
GET /v1/portal/oauth/clients; DELETE /v1/portal/oauth/clients/:clientIdList or revoke connected OAuth clients.
GET /v1/portal/dashboard/domains; GET/PUT /v1/portal/dashboard/config; GET /v1/portal/dashboard/widgetsDashboard domains, per-domain layout configuration, and widget results.
POST /v1/portal/dashboard/add-domain; POST /v1/portal/dashboard/remove-domainCreate dashboard domain watches or remove a domain and its associated configuration.
Account API — Keys, Billing, Usage & Alert Rules | EdgeDNS