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
| Endpoint | Request and response |
|---|---|
GET /v1/keys | Returns data.keys with id, name, prefix, hint, environment, last_used_at, created_at, and settings. Full secrets are not included. |
POST /v1/keys | JSON: 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/:id | Read key details and settings; includes revoked_at. |
PUT /v1/keys/:id | JSON: any of name, ip_allowlist, expires_at. Returns updated details. Does not accept permissions or environment changes. |
DELETE /v1/keys/:id | Revoke 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
| Endpoint | Request and response |
|---|---|
GET /v1/billing/subscription | Returns data.tier, status, current_period_end, cancel_at_period_end. |
GET /v1/billing/usage | Current 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/history | limit defaults to 10, maximum 100. Returns data.invoices with id, amount_cents, status, date, invoice_pdf. |
GET /v1/billing/portal | Required 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
| Endpoint | Request and response |
|---|---|
GET /v1/analytics/usage | Accepts 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-endpoint | Accepts the same period values, but currently returns current UTC-month counters regardless. Returns data.endpoints sorted by request count. |
GET /v1/analytics/usage/by-key | Current-month key usage. Returns data.keys sorted by requests; no period selector. |
GET /v1/analytics/performance | period=current, 7d, or 30d. Returns latency statistics and breakdowns from logged requests. |
GET /v1/analytics/cache | Same period values. Returns cache-hit summary, endpoint breakdown, and daily timeseries. |
GET /v1/analytics/errors | Same period values. Returns error summary and breakdowns from logged requests. |
GET /v1/history/queries | Filters: 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/:id | Returns data.query with parameters, response summary, request_id, timing, status, and other logged metadata. |
GET /v1/history/stats | Optional from and to filters. Returns aggregate query history statistics. |
GET /v1/ping | Authenticated 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
| Endpoint | Request and response |
|---|---|
GET /v1/alerts/rules | Optional enabled=true/false and alert_type. Returns organization alert rules. |
POST /v1/alerts/rules | Create an alert rule using the fields below. |
GET /v1/alerts/rules/:id | Read one rule. |
PUT /v1/alerts/rules/:id | Update enabled, threshold_value, threshold_window_minutes, channels, cooldown_minutes. alert_type is immutable. |
DELETE /v1/alerts/rules/:id | Delete one rule. |
GET /v1/alerts/history | Optional 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/:id | Read one historical alert. |
POST /v1/alerts/history/:id/acknowledge | Acknowledge an alert; optional JSON notes string. |
POST /v1/alerts/history/:id/resolve | Resolve 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.
| Endpoint | Request and response |
|---|---|
GET /v1/portal/ping | Check signed-in portal connectivity. |
GET /v1/portal/keys; POST /v1/portal/keys | List keys or create a key (name, optional environment, ip_allowlist, expires_at). |
GET /v1/portal/keys/:id/reveal | Reveal an encrypted key belonging to the organization. |
POST /v1/portal/keys/ensure-default | Provision or return the managed default key. |
POST /v1/portal/keys/:id/regenerate; POST /v1/portal/keys/regenerate-all | Rotate keys. Bulk rotation requires {"confirm":"regenerate all keys"}. Existing secrets stop working. |
DELETE /v1/portal/keys/:id | Revoke a dashboard-managed key. |
GET /v1/portal/usage; GET /v1/portal/usage/history | Usage reporting and request ledger; history accepts limit, offset, from, to, api_key_id, endpoint. |
GET /v1/portal/billing | Subscription details and billing status for the dashboard. |
POST /v1/portal/billing/portal | Create a Stripe customer portal session; returns data.url. |
POST /v1/portal/billing/checkout; POST /v1/portal/billing/upgrade-checkout | JSON: tier (developer/pro), success_url, cancel_url. Initiates a new paid subscription or upgrade checkout. |
GET /v1/portal/billing/checkout-preview | Required tier=developer/pro. Returns an approximate signup price preview. |
POST /v1/portal/billing/proration-preview; POST /v1/portal/billing/change-plan | JSON: tier (free/developer/pro). Preview or initiate a plan change, subject to subscription state. |
POST /v1/portal/billing/cancel-downgrade | Cancel a scheduled downgrade. |
POST /v1/portal/billing/verify-checkout | JSON: session_id (cs_ prefix). Verify and fulfill the organization’s completed checkout. |
GET/POST /v1/portal/watches and watch subroutes | Dashboard 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-count | List notifications or read the unread count. |
PATCH /v1/portal/notifications/:id/read; POST /v1/portal/notifications/mark-all-read | Mark one notification or all notifications read. |
GET/PATCH/DELETE /v1/portal/profile | Read 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/invite | List members/invitations or invite a member with email and role. |
POST /v1/portal/members/invitations/:token/accept | Accept an invitation as the authenticated invited user. |
PUT /v1/portal/members/:memberId/role; PUT /v1/portal/members/:memberId/permissions | Update role or permissions under organization authorization. |
DELETE /v1/portal/members/:memberId; DELETE /v1/portal/members/invitations/:invitationId | Remove a member or revoke an invitation. |
PUT /v1/portal/members/:memberId/transfer-ownership | Owner-only organization ownership transfer. |
GET /v1/portal/oauth/consent; POST /v1/portal/oauth/consent | GET 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/:clientId | List or revoke connected OAuth clients. |
GET /v1/portal/dashboard/domains; GET/PUT /v1/portal/dashboard/config; GET /v1/portal/dashboard/widgets | Dashboard domains, per-domain layout configuration, and widget results. |
POST /v1/portal/dashboard/add-domain; POST /v1/portal/dashboard/remove-domain | Create dashboard domain watches or remove a domain and its associated configuration. |