{ "openapi": "3.1.0", "info": { "title": "DomainWarn API", "version": "1.0.0", "description": "Public API of DomainWarn: read and write domains, monitors, incidents, events and customers of an organization from scripts, CI pipelines and your own integrations.\n\nAuthenticate with an API token as bearer token; tokens are created in the dashboard under Settings → API and are valid for exactly one organization with the scope `read` or `write`. 300 requests per minute and token. All timestamps are ISO 8601 in UTC.", "contact": { "name": "DomainWarn", "url": "https://domainwarn.com/docs/api", "email": "info@domainwarn.com" }, "termsOfService": "https://domainwarn.com/legal/terms" }, "externalDocs": { "description": "API documentation", "url": "https://domainwarn.com/docs/api" }, "servers": [ { "url": "https://api.domainwarn.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Organization", "description": "The organization the token belongs to" }, { "name": "Overview", "description": "Summary as on the dashboard home page" }, { "name": "Domains", "description": "Create, update, pause and check monitored domains" }, { "name": "Monitors", "description": "Individual checks per domain, their results and availability" }, { "name": "DNS", "description": "DNS snapshots and changes" }, { "name": "Incidents", "description": "Problems with cause, status and acknowledgement" }, { "name": "Events", "description": "Detected changes and history" }, { "name": "Customers", "description": "Customers domains are assigned to" } ], "paths": { "/organizations": { "get": { "operationId": "listOrganizations", "tags": [ "Organization" ], "summary": "Organization of the token", "description": "Returns exactly the organization the token belongs to, with slug, plan and the role of the token. Useful to look up the slug for all further calls.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/dashboard": { "get": { "operationId": "getDashboard", "tags": [ "Overview" ], "summary": "Overview", "description": "Counters per health state, open incidents, changes of the last 24 hours, plan usage and history of the last 14 days. The response carries an ETag; with `If-None-Match` the server answers 304 when nothing changed.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "ETag of the previous response; if nothing changed the server answers 304 without a body", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } } } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Identifier of this state for `If-None-Match`" }, "Cache-Control": { "schema": { "type": "string", "example": "private, max-age=30" }, "description": "Short lifetime, the response is per organization" } } }, "304": { "description": "Unchanged since the ETag in `If-None-Match`, no body", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Identifier of this state for `If-None-Match`" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/usage": { "get": { "operationId": "getUsage", "tags": [ "Overview" ], "summary": "Plan usage", "description": "Limits of the effective plan and current usage: domains, monitors, members, channels and checks of the last 24 hours.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains": { "get": { "operationId": "listDomains", "tags": [ "Domains" ], "summary": "List domains", "description": "All domains of the organization with health, customer and number of open incidents, paginated. Monitors are not included here; use the single fetch for them.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "status", "in": "query", "required": false, "description": "Health states, comma-separated: healthy, warning, critical, unknown", "schema": { "type": "string", "example": "critical,warning" } }, { "name": "customer", "in": "query", "required": false, "description": "Only domains of this customer", "schema": { "type": "string", "format": "uuid" } }, { "name": "cms", "in": "query", "required": false, "description": "CMS keys, comma-separated; `none` for reachable without a known system, `unknown` for not detected yet", "schema": { "type": "string", "example": "wordpress" } }, { "name": "search", "in": "query", "required": false, "description": "Part of the domain name", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order, minus for descending", "schema": { "type": "string", "enum": [ "name", "-name", "health_status", "-health_status", "created_at", "-created_at", "last_checked_at", "-last_checked_at" ], "default": "name" } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (1 to 200)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "links": { "$ref": "#/components/schemas/Links" }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createDomain", "tags": [ "Domains" ], "summary": "Create a domain", "description": "Creates the domain with the default monitors and starts the first check. The domain limit of the plan applies; above it the server answers 422.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Domain" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "description": "Domain, Unicode or punycode; subdomains and schemes are stripped" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Customer the domain is assigned to" }, "run_checks": { "type": "boolean", "default": true, "description": "Start the first check immediately" } } }, "example": { "name": "kunde.de", "customer_id": null } } } } } }, "/orgs/{organization}/domains/export.csv": { "get": { "operationId": "exportDomainsCsv", "tags": [ "Domains" ], "summary": "Domains as CSV", "description": "The same list as when listing, as a CSV file with all rows instead of pages (UTF-8 with BOM, `Content-Disposition: attachment`). Columns: domain, customer, health, cms, cms_version, registrar, domain_expires_at, certificate_target, certificate_valid_to, certificate_days_left, open_incidents, last_checked_at, paused, dashboard_url. The certificate is the one of the apex domain on port 443, otherwise of the first enabled certificate monitor (`certificate_target` names it).\n\nA read token is sufficient (`read`).\n\nOwn limit: 30 calls per hour and organization.", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "status", "in": "query", "required": false, "description": "Health states, comma-separated: healthy, warning, critical, unknown", "schema": { "type": "string", "example": "critical,warning" } }, { "name": "customer", "in": "query", "required": false, "description": "Only domains of this customer", "schema": { "type": "string", "format": "uuid" } }, { "name": "cms", "in": "query", "required": false, "description": "CMS keys, comma-separated; `none` for reachable without a known system, `unknown` for not detected yet", "schema": { "type": "string", "example": "wordpress" } }, { "name": "search", "in": "query", "required": false, "description": "Part of the domain name", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order, minus for descending", "schema": { "type": "string", "enum": [ "name", "-name", "health_status", "-health_status", "created_at", "-created_at", "last_checked_at", "-last_checked_at" ], "default": "name" } }, { "name": "delimiter", "in": "query", "required": false, "description": "Delimiter; without it semicolon for language de (Excel), comma otherwise", "schema": { "type": "string", "enum": [ "comma", "semicolon" ] } } ], "responses": { "200": { "description": "CSV file", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/cms": { "get": { "operationId": "listDomainCms", "tags": [ "Domains" ], "summary": "Detected systems", "description": "Which CMS and shop systems were detected on the domains, with counts; `meta.none` counts reachable domains without a known system, `meta.unknown` those not detected yet. Values for the `cms` filter of the domain list.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "CMS key" }, "name": { "type": "string", "description": "Name" }, "count": { "type": "integer", "description": "Domains" } } } }, "meta": { "type": "object", "properties": { "none": { "type": "integer", "description": "Reachable without a known system" }, "unknown": { "type": "integer", "description": "Not detected yet" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/bulk": { "post": { "operationId": "bulkCreateDomains", "tags": [ "Domains" ], "summary": "Create domains in bulk", "description": "Up to 200 domains per call, as a list or as text with one domain per line (comma, semicolon and whitespace also separate; lines starting with # are skipped). Invalid or duplicate domains end up in `meta.errors`, the rest are created.\n\nRequires a token with write scope (`write`).\n\nOwn limit: 3 calls per hour and organization.", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } } ], "responses": { "201": { "description": "Created domains and errors per input", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "meta": { "type": "object", "properties": { "created": { "type": "integer" }, "failed": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "domains": { "type": "array", "items": { "type": "string" }, "maxItems": 200, "description": "List of domains (alternative to `text`)" }, "text": { "type": "string", "maxLength": 20000, "description": "Domains as text (alternative to `domains`)" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Customer for all created domains" } } }, "example": { "text": "kunde-a.de\nkunde-b.de\nshop.kunde-c.com", "customer_id": null } } } } } }, "/orgs/{organization}/domains/import/zone-file": { "post": { "operationId": "previewZoneFileImport", "tags": [ "Domains" ], "summary": "Parse a zone file", "description": "Reads a BIND zone file and returns the website hostnames (A, AAAA, CNAME) as a preview, each with a flag whether it is already monitored. At most 200 per call, further pages via `offset` = `next_offset`. Creates nothing: the confirmed selection goes to the import.\n\nRequires a token with write scope (`write`).\n\nOwn limit: 60 calls per minute and organization.", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "origin": { "type": [ "string", "null" ], "description": "Detected zone" }, "records": { "type": "integer", "description": "Records read" }, "hostnames": { "type": "array", "items": { "type": "object", "properties": { "hostname": { "type": "string" }, "is_apex": { "type": "boolean", "description": "The zone itself" }, "already_monitored": { "type": "boolean", "description": "A website monitor for this hostname already exists" } } } }, "total": { "type": "integer", "description": "Total hostnames" }, "offset": { "type": "integer", "description": "First entry of this page" }, "next_offset": { "type": [ "integer", "null" ], "description": "Offset of the next page, null at the end" }, "truncated": { "type": "boolean", "description": "More hostnames than one page" }, "limit": { "type": "integer", "description": "Hostnames per page" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 500000, "description": "Contents of the zone file" }, "origin": { "type": [ "string", "null" ], "maxLength": 255, "description": "Zone for files without `$ORIGIN` (e.g. example.com); if missing with relative names the server answers 422" }, "offset": { "type": [ "integer", "null" ], "minimum": 0, "description": "First entry of the page (from `next_offset`)" } } }, "example": { "text": "$ORIGIN kunde.de.\n@ IN A 203.0.113.10\nwww IN CNAME kunde.de.\nshop IN A 203.0.113.11" } } } } } }, "/orgs/{organization}/domains/import/commit": { "post": { "operationId": "commitDomainImport", "tags": [ "Domains" ], "summary": "Confirm an import", "description": "Creates the confirmed list from a zone file in the background, up to 5000 domains per import. The response (202) is the import with its ID; `GET /domains/import/{import}` reports the progress until `status` is done or failed. Unlike bulk creation, the monitors start at their regular time instead of immediately. Once the plan's domain limit is reached, the remaining names are rejected with the same reason.\n\nRequires a token with write scope (`write`).\n\nOwn limit: 10 imports per hour and organization.", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } } ], "responses": { "202": { "description": "The created import (status queued)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DomainImport" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "minItems": 1, "maxItems": 5000, "description": "Confirmed domains or hostnames" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Customer for all created domains" } } }, "example": { "domains": [ "kunde.de", "shop.kunde.de" ], "customer_id": null } } } } } }, "/orgs/{organization}/domains/import/{import}": { "get": { "operationId": "getDomainImport", "tags": [ "Domains" ], "summary": "Get import progress", "description": "State of an import: counters per batch and, once finished, the list of rejected or skipped names with reason. Poll every few seconds until `status` is done or failed. Agency-internal: customer accounts cannot see imports.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "import", "in": "path", "required": true, "description": "Import ID from the confirm response", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DomainImport" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/{domain}": { "get": { "operationId": "getDomain", "tags": [ "Domains" ], "summary": "Get a domain", "description": "A single domain with all monitors, their latest findings and the number of open incidents.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Domain" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "updateDomain", "tags": [ "Domains" ], "summary": "Update a domain", "description": "Assign a customer, switch monitoring on or off, or set notification rules for this domain only. Only fields that are sent change.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Domain" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Customer or null to unassign" }, "is_active": { "type": "boolean", "description": "false pauses monitoring indefinitely, true resumes it" }, "notification_overrides": { "type": [ "object", "null" ], "description": "Notification overrides", "properties": { "failure_minutes": { "type": "integer", "description": "Minutes before a failure is reported (1 to 1440)", "minimum": 1, "maximum": 1440 }, "recovery_minutes": { "type": "integer", "description": "Minutes before recovery is reported (1 to 1440)", "minimum": 1, "maximum": 1440 }, "min_severity": { "type": "string", "enum": [ "info", "warning", "critical" ], "description": "Lowest severity that is reported" }, "ignore_quiet_hours": { "type": "boolean", "description": "Notify during quiet hours as well" }, "notify_on_change": { "type": "array", "items": { "type": "string" }, "description": "Change types that are reported" } } } } }, "example": { "customer_id": "3f9c1a52-6a2e-4c0e-9d4b-1c9a1a0e5b77", "notification_overrides": { "min_severity": "critical" } } } } } }, "delete": { "operationId": "deleteDomain", "tags": [ "Domains" ], "summary": "Delete a domain", "description": "Permanently removes the domain with its monitors, results, incidents and events.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted, no content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/{domain}/pause": { "post": { "operationId": "pauseDomain", "tags": [ "Domains" ], "summary": "Pause a domain", "description": "Suspends monitoring until a point in time, e.g. during a migration. Without `until` the pause is lifted. Open incidents remain.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Domain" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "until": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the pause, in the future; null lifts the pause" } } }, "example": { "until": "2026-10-01T06:00:00Z" } } } } } }, "/orgs/{organization}/domains/{domain}/monitoring": { "patch": { "operationId": "setMonitoringGroups", "tags": [ "Domains" ], "summary": "Switch monitoring groups", "description": "Switches the groups website (`web`: http, tls, ct_log, redirects, ipv6), mail (`mail`: mx, spf, dkim, dmarc, mta_sts, tls_rpt, bimi, reverse_dns, smtp, dane) and DNS (`dns`: dns, dnssec, domain, blacklist, caa, nameservers) on or off. Groups that are switched off close their open incidents.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Domain" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "groups" ], "properties": { "groups": { "type": "object", "properties": { "web": { "type": "boolean" }, "mail": { "type": "boolean" }, "dns": { "type": "boolean" } }, "description": "Groups with the desired state; groups not mentioned stay unchanged" } } }, "example": { "groups": { "mail": false } } } } } } }, "/orgs/{organization}/domains/{domain}/detect-cms": { "post": { "operationId": "detectDomainCms", "tags": [ "Domains" ], "summary": "Detect the system again", "description": "Queues CMS and shop system detection for the domain; the result appears in the domain's `cms`.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Detection queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "queued": { "type": "boolean", "description": "Queued" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/{domain}/check-now": { "post": { "operationId": "checkDomainNow", "tags": [ "Domains" ], "summary": "Check now", "description": "Queues all enabled monitors of the domain immediately, e.g. after a deploy or a DNS change. Results show up in the monitors a few seconds later.\n\nRequires a token with write scope (`write`).\n\nOwn limit: 5 per domain and hour, 60 per organization and hour.", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Checks queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dispatched": { "type": "integer", "description": "Number of queued checks" }, "requested_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/{domain}/fixes": { "get": { "operationId": "listFixes", "tags": [ "DNS" ], "summary": "Missing records", "description": "Suggestions for missing DNS records (DMARC, SPF, TLS-RPT, CAA) derived from the current findings of the domain, with the connected Cloudflare integrations and whether the zone is hosted at Cloudflare.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Fix" } }, "meta": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "name": { "type": "string" } } } }, "dns_hosted_at_cloudflare": { "type": "boolean", "description": "All name servers of the domain point to Cloudflare (only then can records be created)" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/{domain}/fixes/{fix}/apply": { "post": { "operationId": "applyFix", "tags": [ "DNS" ], "summary": "Create the record at Cloudflare", "description": "Creates the suggested record through the given Cloudflare integration. Additive only: existing records are never changed; if a matching record already exists or the zone is not (or no longer) hosted at Cloudflare, the server responds with 422. The monitor is re-checked afterwards.\n\nRequires a token with write scope (`write`).\n\nOwn limit: 20 per minute.", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "fix", "in": "path", "required": true, "description": "Suggestion key from the list of missing records", "schema": { "type": "string", "pattern": "^[a-z_]+$" } } ], "responses": { "200": { "description": "Record created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "fix": { "$ref": "#/components/schemas/Fix" }, "record_id": { "type": "string", "description": "ID of the created record at Cloudflare" }, "zone": { "type": "string", "description": "Cloudflare zone name" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "integration_id" ], "properties": { "integration_id": { "type": "string", "format": "uuid", "description": "Cloudflare integration of the organization" }, "rua": { "type": "string", "description": "Report address for dmarc_missing and tls_rpt_missing (required for these suggestions)" }, "senders": { "type": "string", "description": "Additional SPF mechanisms for spf_missing, comma-separated (include:…, ip4:…, ip6:…, a, mx); empty confirms that no other services send" } } }, "example": { "integration_id": "3f9c1a52-6a2e-4c0e-9d4b-1c9a1a0e5b77", "rua": "dmarc-reports@agentur.de" } } } } } }, "/orgs/{organization}/domains/{domain}/suggestions": { "get": { "operationId": "listHostnameSuggestions", "tags": [ "Monitors" ], "summary": "Hostname suggestions", "description": "Hostnames under the domain that appear in certificate transparency logs but are not monitored yet. Open ones by default; with `all=1` also accepted and dismissed ones, in pages of 200.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "all", "in": "query", "required": false, "description": "Include decided suggestions as well", "schema": { "type": "boolean", "default": false } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HostnameSuggestion" } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "has_more": { "type": "boolean", "description": "Another page exists" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/suggestions/{suggestion}/accept": { "post": { "operationId": "acceptHostnameSuggestion", "tags": [ "Monitors" ], "summary": "Accept a suggestion", "description": "Creates a website monitor for the hostname and marks the suggestion as accepted. 422 if the hostname does not belong to the domain or the limit of hostnames per domain is reached.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "suggestion", "in": "path", "required": true, "description": "Hostname suggestion ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HostnameSuggestion" }, "monitor": { "oneOf": [ { "$ref": "#/components/schemas/Monitor" }, { "type": "null" } ], "description": "Created monitor; null if it already existed" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The suggestion has already been decided", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/suggestions/{suggestion}/dismiss": { "post": { "operationId": "dismissHostnameSuggestion", "tags": [ "Monitors" ], "summary": "Dismiss a suggestion", "description": "Marks the suggestion as dismissed; the hostname is not suggested again.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "suggestion", "in": "path", "required": true, "description": "Hostname suggestion ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dismissed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HostnameSuggestion" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The suggestion has already been decided", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/{domain}/monitors": { "get": { "operationId": "listMonitors", "tags": [ "Monitors" ], "summary": "Monitors of a domain", "description": "All monitors of the domain with status, latest findings and raw data, sorted by check type and target.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Monitor" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createMonitor", "tags": [ "Monitors" ], "summary": "Create a monitor", "description": "Additional monitor, e.g. another URL or a mail server certificate. Targets must belong to the domain; only for `tls` any public hostname is allowed. The interval is capped at the minimum of the plan.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Monitor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "target" ], "properties": { "type": { "type": "string", "enum": [ "http", "tls", "dns", "mx", "spf", "dmarc", "domain", "dkim", "dnssec", "mta_sts", "blacklist", "tls_rpt", "bimi", "smtp", "reverse_dns", "ct_log", "redirects", "caa", "nameservers", "ipv6", "dane" ], "description": "Check type" }, "target": { "type": "string", "maxLength": 255, "description": "URL (http) or hostname; https:// is added when the scheme is missing" }, "interval_seconds": { "type": "integer", "minimum": 60, "maximum": 604800, "description": "Check interval in seconds" }, "config": { "type": "object", "properties": { "port": { "type": "integer", "enum": [ 443, 8443, 465, 587, 25, 993, 143, 995, 110 ] }, "starttls": { "type": [ "string", "null" ], "enum": [ "smtp", "imap", "pop3", null ] } }, "description": "tls only: port and STARTTLS protocol" } } }, "example": { "type": "tls", "target": "mail.kunde.de", "config": { "port": 587, "starttls": "smtp" } } } } } } }, "/orgs/{organization}/monitors/{monitor}": { "patch": { "operationId": "updateMonitor", "tags": [ "Monitors" ], "summary": "Update a monitor", "description": "Interval, activation and configuration per check type: `expected_status` and `slow_ms` (http), `selectors` (dkim). A disabled monitor closes its open incidents.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "monitor", "in": "path", "required": true, "description": "Monitor ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Monitor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "interval_seconds": { "type": "integer", "minimum": 60, "maximum": 604800, "description": "Check interval in seconds" }, "is_enabled": { "type": "boolean", "description": "Enabled" }, "config": { "type": "object", "properties": { "expected_status": { "type": "array", "items": { "type": "integer", "minimum": 100, "maximum": 599 } }, "slow_ms": { "type": "integer", "minimum": 100, "maximum": 60000 }, "selectors": { "type": "array", "items": { "type": "string", "maxLength": 63 }, "maxItems": 20 } }, "description": "Expected HTTP status codes, threshold for \"slow\" in ms (http) or DKIM selectors (dkim)" } } }, "example": { "config": { "expected_status": [ 200, 301 ], "slow_ms": 2000 } } } } } }, "delete": { "operationId": "deleteMonitor", "tags": [ "Monitors" ], "summary": "Delete a monitor", "description": "Removes the monitor and closes its open incidents.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "monitor", "in": "path", "required": true, "description": "Monitor ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted, no content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/maintenance-windows": { "get": { "operationId": "listMaintenanceWindows", "tags": [ "Monitors" ], "summary": "List maintenance windows", "description": "All maintenance windows of the organization, enabled first; with `domain` only those affecting that domain (its own, its customer's and organization-wide ones).\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "query", "required": false, "description": "Only windows affecting this domain", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MaintenanceWindow" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createMaintenanceWindow", "tags": [ "Monitors" ], "summary": "Create a maintenance window", "description": "One-off (`starts_at`, `ends_at`) or weekly (`weekdays`, `time_from`, `time_to` in `timezone`). With `domain_id` it applies to one domain, with `customer_id` to all domains of the customer, with neither to the whole organization. No incidents or notifications are raised while it is active.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MaintenanceWindow" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "kind" ], "properties": { "name": { "type": "string", "maxLength": 120, "description": "Name" }, "kind": { "type": "string", "enum": [ "once", "weekly" ], "description": "One-off or weekly" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Customer whose domains are affected" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Single domain (resets `customer_id`)" }, "starts_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Start, one-off (required for `once`)" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "End, one-off, after the start (required for `once`)" }, "weekdays": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "maxItems": 7, "description": "Weekdays 1 (Monday) to 7 (Sunday) (required for `weekly`)" }, "time_from": { "type": [ "string", "null" ], "pattern": "^\\d{2}:\\d{2}$", "description": "Start HH:MM (required for `weekly`)" }, "time_to": { "type": [ "string", "null" ], "pattern": "^\\d{2}:\\d{2}$", "description": "End HH:MM, different from the start; before the start the window spans midnight (required for `weekly`)" }, "timezone": { "type": "string", "default": "Europe/Berlin", "description": "Time zone for weekdays and times" }, "is_enabled": { "type": "boolean", "default": true, "description": "Enabled" } } }, "example": { "name": "Nächtliches Deploy", "kind": "weekly", "customer_id": "3f9c1a52-6a2e-4c0e-9d4b-1c9a1a0e5b77", "weekdays": [ 2, 4 ], "time_from": "02:00", "time_to": "03:00", "timezone": "Europe/Berlin" } } } } } }, "/orgs/{organization}/maintenance-windows/{window}": { "patch": { "operationId": "updateMaintenanceWindow", "tags": [ "Monitors" ], "summary": "Update a maintenance window", "description": "Same fields as on create, all optional; only fields that are sent change. The rules per kind apply to the state after the change.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "window", "in": "path", "required": true, "description": "Maintenance window ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MaintenanceWindow" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "maxLength": 120, "description": "Name" }, "kind": { "type": "string", "enum": [ "once", "weekly" ], "description": "One-off or weekly" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Customer or null" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Domain or null" }, "starts_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Start, one-off" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "End, one-off" }, "weekdays": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "maxItems": 7, "description": "Weekdays 1 to 7" }, "time_from": { "type": [ "string", "null" ], "pattern": "^\\d{2}:\\d{2}$", "description": "Start HH:MM" }, "time_to": { "type": [ "string", "null" ], "pattern": "^\\d{2}:\\d{2}$", "description": "End HH:MM" }, "timezone": { "type": "string", "description": "Time zone" }, "is_enabled": { "type": "boolean", "description": "Enabled" } } }, "example": { "is_enabled": false } } } } }, "delete": { "operationId": "deleteMaintenanceWindow", "tags": [ "Monitors" ], "summary": "Delete a maintenance window", "description": "Requires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "window", "in": "path", "required": true, "description": "Maintenance window ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted, no content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/monitors/{monitor}/results": { "get": { "operationId": "listCheckResults", "tags": [ "Monitors" ], "summary": "Check results", "description": "Single checks of a monitor, newest first, cursor-paginated. The cursor of the next page is in `links.next`.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "monitor", "in": "path", "required": true, "description": "Monitor ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Only checks from this time on", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Only checks up to this time", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (1 to 500)", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor of the next page, taken from `meta.next_cursor` of the previous response", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckResult" } }, "links": { "type": "object", "properties": { "next": { "type": [ "string", "null" ], "description": "Cursor of the next page" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/monitors/{monitor}/uptime": { "get": { "operationId": "getUptime", "tags": [ "Monitors" ], "summary": "Availability and response time", "description": "Availability, response times (median, 95th percentile) and downtime per range, plus data points for charts.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "monitor", "in": "path", "required": true, "description": "Monitor ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "range", "in": "query", "required": false, "description": "Range", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ], "default": "24h" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Uptime" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/{domain}/dns": { "get": { "operationId": "getDns", "tags": [ "DNS" ], "summary": "Current DNS records", "description": "The latest DNS snapshot of the domain with all records per type; null while none exists yet.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/DnsSnapshot" }, { "type": "null" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/{domain}/dns/snapshots": { "get": { "operationId": "listDnsSnapshots", "tags": [ "DNS" ], "summary": "DNS history", "description": "All snapshots of the domain, newest first, without records (use the diff for those). Each snapshot stands for a period with unchanged configuration.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DnsSnapshot" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/{domain}/dns/diff": { "get": { "operationId": "diffDnsSnapshots", "tags": [ "DNS" ], "summary": "Compare two DNS snapshots", "description": "Both snapshots with records and the differences between them (added, removed and changed records per type).\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "ID of the older snapshot", "schema": { "type": "string", "format": "uuid" } }, { "name": "to", "in": "query", "required": true, "description": "ID of the newer snapshot", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/DnsSnapshot" }, "to": { "$ref": "#/components/schemas/DnsSnapshot" }, "diff": { "type": "object", "additionalProperties": true, "description": "Differences per record type" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/incidents": { "get": { "operationId": "listIncidents", "tags": [ "Incidents" ], "summary": "List incidents", "description": "By default only open and acknowledged incidents, open and critical first; cursor-paginated.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "status", "in": "query", "required": false, "description": "`open` (open and acknowledged), `all` or statuses comma-separated: open, acknowledged, resolved", "schema": { "type": "string", "default": "open", "example": "open" } }, { "name": "severity", "in": "query", "required": false, "description": "Severities, comma-separated: info, warning, critical", "schema": { "type": "string", "example": "critical,warning" } }, { "name": "domain", "in": "query", "required": false, "description": "Only incidents of this domain", "schema": { "type": "string", "format": "uuid" } }, { "name": "customer", "in": "query", "required": false, "description": "Only domains of this customer", "schema": { "type": "string", "format": "uuid" } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (1 to 200)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor of the next page, taken from `meta.next_cursor` of the previous response", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "links": { "$ref": "#/components/schemas/Links" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/incidents/{incident}": { "get": { "operationId": "getIncident", "tags": [ "Incidents" ], "summary": "Get an incident", "description": "A single incident with domain, monitor, cause and the name of the person who acknowledged it.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "incident", "in": "path", "required": true, "description": "Incident ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Incident" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/incidents/{incident}/acknowledge": { "post": { "operationId": "acknowledgeIncident", "tags": [ "Incidents" ], "summary": "Acknowledge an incident", "description": "Marks the incident as seen; reminders stop, the recovery notice is still sent.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "incident", "in": "path", "required": true, "description": "Incident ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Incident" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/events": { "get": { "operationId": "listEvents", "tags": [ "Events" ], "summary": "List events", "description": "Detected changes and incident transitions of all domains, newest first, cursor-paginated. Suitable for your own reports or a change log.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "severity", "in": "query", "required": false, "description": "Severities, comma-separated: info, warning, critical", "schema": { "type": "string", "example": "critical,warning" } }, { "name": "type", "in": "query", "required": false, "description": "Event types, comma-separated", "schema": { "type": "string", "example": "dns.record_changed,tls.renewed" } }, { "name": "domain", "in": "query", "required": false, "description": "Only events of this domain", "schema": { "type": "string", "format": "uuid" } }, { "name": "customer", "in": "query", "required": false, "description": "Only domains of this customer", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Only events from this time on", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Only events up to this time", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (1 to 200)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor of the next page, taken from `meta.next_cursor` of the previous response", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "links": { "$ref": "#/components/schemas/Links" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/domains/{domain}/timeline": { "get": { "operationId": "getDomainTimeline", "tags": [ "Events" ], "summary": "Timeline of a domain", "description": "Events of a single domain, newest first; same filters as for all events.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "domain", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "severity", "in": "query", "required": false, "description": "Severities, comma-separated: info, warning, critical", "schema": { "type": "string", "example": "critical,warning" } }, { "name": "type", "in": "query", "required": false, "description": "Event types, comma-separated", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "From time", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Up to time", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (1 to 200)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor of the next page, taken from `meta.next_cursor` of the previous response", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "links": { "$ref": "#/components/schemas/Links" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/customers": { "get": { "operationId": "listCustomers", "tags": [ "Customers" ], "summary": "List customers", "description": "Customers of the organization with their number of domains, alphabetical; archived ones only on request.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "search", "in": "query", "required": false, "description": "Part of name or reference", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "true returns only archived, false only active (default)", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page (1 to 200)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "links": { "$ref": "#/components/schemas/Links" }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createCustomer", "tags": [ "Customers" ], "summary": "Create a customer", "description": "Requires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 160, "description": "Name, unique per organization" }, "reference": { "type": [ "string", "null" ], "maxLength": 64, "description": "Your own reference" }, "notes": { "type": [ "string", "null" ], "maxLength": 5000, "description": "Notes" }, "contact_email": { "type": [ "string", "null" ], "format": "email", "description": "Contact address for reports" }, "monthly_report": { "type": "boolean", "description": "Send the monthly report" }, "report_locale": { "type": [ "string", "null" ], "enum": [ "de", "en", null ], "description": "Report language" } } }, "example": { "name": "Musterfirma GmbH", "reference": "K-1042", "contact_email": "it@musterfirma.de", "monthly_report": true, "report_locale": "de" } } } } } }, "/orgs/{organization}/customers/{customer}": { "get": { "operationId": "getCustomer", "tags": [ "Customers" ], "summary": "Get a customer", "description": "A read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "customer", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "updateCustomer", "tags": [ "Customers" ], "summary": "Update a customer", "description": "Same fields as on create, plus `is_archived`. `name` must always be sent.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "customer", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 160, "description": "Name" }, "reference": { "type": [ "string", "null" ], "maxLength": 64, "description": "Your own reference" }, "notes": { "type": [ "string", "null" ], "maxLength": 5000, "description": "Notes" }, "contact_email": { "type": [ "string", "null" ], "format": "email", "description": "Contact address" }, "is_archived": { "type": "boolean", "description": "Archive or restore" }, "monthly_report": { "type": "boolean", "description": "Send the monthly report" }, "report_locale": { "type": [ "string", "null" ], "enum": [ "de", "en", null ], "description": "Report language" } } }, "example": { "name": "Musterfirma GmbH", "is_archived": true } } } } }, "delete": { "operationId": "deleteCustomer", "tags": [ "Customers" ], "summary": "Delete a customer", "description": "Removes the customer; their domains remain and only lose the assignment.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "customer", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted, no content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/customers/{customer}/report": { "get": { "operationId": "getCustomerReport", "tags": [ "Customers" ], "summary": "Get the monthly report", "description": "The customer's monthly report as data: summary, per domain availability, downtime, incidents and certificate, plus incidents, changes and upcoming expiries. Without `month` the previous month, language via `locale`.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "customer", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "query", "required": false, "description": "Report month as YYYY-MM; defaults to the previous month", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "example": "2026-08" } }, { "name": "locale", "in": "query", "required": false, "description": "Report language (texts, date formats); without it the customer's report language, else the organization's. Accept-Language does not apply here.", "schema": { "type": "string", "enum": [ "de", "en" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerReport" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/customers/{customer}/report/pdf": { "get": { "operationId": "getCustomerReportPdf", "tags": [ "Customers" ], "summary": "Monthly report as PDF", "description": "The same report as PDF; `download=1` returns it as an attachment instead of inline.\n\nA read token is sufficient (`read`).", "x-scope": "read", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "customer", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "query", "required": false, "description": "Report month as YYYY-MM; defaults to the previous month", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "example": "2026-08" } }, { "name": "locale", "in": "query", "required": false, "description": "Report language (texts, date formats); without it the customer's report language, else the organization's. Accept-Language does not apply here.", "schema": { "type": "string", "enum": [ "de", "en" ] } }, { "name": "download", "in": "query", "required": false, "description": "As download (Content-Disposition attachment)", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "PDF file", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/customers/{customer}/report/share": { "post": { "operationId": "shareCustomerReport", "tags": [ "Customers" ], "summary": "Share the report", "description": "Creates a signed link to the PDF, valid for 60 days, retrievable without login – to pass on to the customer.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "customer", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "query", "required": false, "description": "Report month as YYYY-MM; defaults to the previous month", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "example": "2026-08" } }, { "name": "locale", "in": "query", "required": false, "description": "Report language (texts, date formats); without it the customer's report language, else the organization's. Accept-Language does not apply here.", "schema": { "type": "string", "enum": [ "de", "en" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Signed link" }, "expires_at": { "type": "string", "format": "date-time", "description": "Valid until" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orgs/{organization}/customers/{customer}/status-page": { "post": { "operationId": "enableCustomerStatusPage", "tags": [ "Customers" ], "summary": "Enable the status page", "description": "Creates the token of the customer's public status page (reachable without login); an existing one is replaced and the old address stops working. The address is in `status_page_url`. For archived customers the server answers 422.\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "customer", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Enabled, address in `status_page_url`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "disableCustomerStatusPage", "tags": [ "Customers" ], "summary": "Disable the status page", "description": "Deletes the token; the address answers 404 afterwards. Returns the customer (`status_page_url` is null).\n\nRequires a token with write scope (`write`).", "x-scope": "write", "parameters": [ { "name": "organization", "in": "path", "required": true, "description": "Organization slug as shown in the dashboard URL and under Settings → API. A token only reaches its own organization; others respond with 404.", "schema": { "type": "string", "example": "meine-agentur" } }, { "name": "customer", "in": "path", "required": true, "description": "Customer ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API token from the dashboard (Settings → API) in the header `Authorization: Bearer `; also send `Accept: application/json`." } }, "responses": { "Unauthorized": { "description": "Token missing, expired or revoked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "Token is not allowed to do this (read token on a writing method or a blocked area)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "Organization or object not found, also for a foreign organization", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PaymentRequired": { "description": "Organization suspended or without an active plan", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlanProblem" } } } }, "ValidationError": { "description": "Invalid input, messages per field in `errors`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "TooManyRequests": { "description": "Limit exceeded; `Retry-After` gives the wait time in seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "Fix": { "type": "object", "description": "Suggested missing DNS record that DomainWarn can create through a Cloudflare integration", "properties": { "key": { "type": "string", "description": "Suggestion key, e.g. dmarc_missing, spf_missing, tls_rpt_missing, caa_missing" }, "finding": { "type": "string", "description": "Finding that triggers the suggestion" }, "type": { "type": "string", "description": "Record type (TXT, CAA)" }, "name": { "type": "string", "description": "Record name" }, "content": { "type": "string", "description": "Record content as it would be created" }, "monitor_id": { "type": "string", "format": "uuid", "description": "Monitor whose finding triggers the suggestion" }, "note_key": { "type": "string", "description": "Key of the note for the suggestion, e.g. dmarc_missing, spf_include, spf_mx, caa_missing; the dashboard translates it" }, "note_params": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Placeholders of the note, e.g. provider (spf_include) or ca (caa_missing)" }, "input": { "type": "string", "enum": [ "rua", "senders" ], "description": "Required input when applying: report address (rua) or sending services (senders); absent when none is needed" }, "input_default": { "type": "string", "description": "Suggested value for the input (only with `input`)" } }, "required": [ "key", "finding", "type", "name", "content", "monitor_id", "note_key", "note_params" ] }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Organization ID" }, "name": { "type": "string", "description": "Name" }, "slug": { "type": "string", "description": "Slug used in `/orgs/{organization}`" }, "plan": { "type": "string", "enum": [ "trial", "free", "freelancer", "agency", "agency_pro" ], "description": "Effective plan: trial during the trial period (free afterwards), otherwise the booked or gifted plan" }, "monitoring_active": { "type": "boolean", "description": "Whether checks are running (false while the organization is suspended)" }, "trial_days_left": { "type": [ "integer", "null" ], "description": "Remaining days of the trial period, null outside the trial" }, "timezone": { "type": "string", "description": "Organization time zone" }, "locale": { "type": "string", "enum": [ "de", "en" ], "description": "Organization language" }, "suspended": { "type": "boolean", "description": "Suspended by the operator" }, "role": { "type": "string", "enum": [ "viewer", "member" ], "description": "Role of the token: viewer (read) or member (write)" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Creation time" } } }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Customer ID" }, "name": { "type": "string", "description": "Name, unique per organization" }, "reference": { "type": [ "string", "null" ], "description": "Your own reference, e.g. a customer number" }, "notes": { "type": [ "string", "null" ], "description": "Notes" }, "contact_email": { "type": [ "string", "null" ], "format": "email", "description": "Contact address for reports" }, "is_archived": { "type": "boolean", "description": "Archived" }, "monthly_report": { "type": "boolean", "description": "Monthly report by e-mail" }, "report_locale": { "type": [ "string", "null" ], "enum": [ "de", "en", null ], "description": "Report language" }, "last_report_sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last report sent" }, "status_page_url": { "type": [ "string", "null" ], "format": "uri", "description": "Public status page of the customer (contains the token); null while none is enabled" }, "domains_count": { "type": "integer", "description": "Number of assigned domains" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Creation time" } } }, "Monitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor ID" }, "domain_id": { "type": "string", "format": "uuid", "description": "Domain ID" }, "type": { "type": "string", "enum": [ "http", "tls", "dns", "mx", "spf", "dmarc", "domain", "dkim", "dnssec", "mta_sts", "blacklist", "tls_rpt", "bimi", "smtp", "reverse_dns", "ct_log", "redirects", "caa", "nameservers", "ipv6", "dane" ], "description": "Check type" }, "target": { "type": "string", "description": "Target: URL for http, hostname otherwise" }, "config": { "type": "object", "additionalProperties": true, "description": "Configuration per check type, e.g. expected_status and slow_ms (http), port and starttls (tls), selectors (dkim)" }, "interval_seconds": { "type": "integer", "description": "Check interval in seconds (capped by the plan)" }, "is_enabled": { "type": "boolean", "description": "Enabled" }, "current_status": { "type": "string", "enum": [ "ok", "warning", "critical", "unknown" ], "description": "Current status" }, "next_check_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Next check" }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last check" }, "consecutive_failures": { "type": "integer", "description": "Consecutive failures" }, "consecutive_errors": { "type": "integer", "description": "Consecutive check errors (the check itself could not run)" }, "failure_locations": { "type": "array", "items": { "type": "string" }, "description": "Check locations that see the current failure; empty while the check passes" }, "is_volatile": { "type": "boolean", "description": "Result flaps between checks" }, "last_payload": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Raw data of the last check, structure depends on the type" }, "last_payload_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the raw data" }, "last_findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" }, "description": "Findings of the last check" }, "pending_change": { "type": "boolean", "description": "Change detected, confirmation check pending" }, "last_fingerprint": { "type": [ "string", "null" ], "description": "Fingerprint of the last observed configuration" } } }, "Finding": { "type": "object", "description": "Check finding, text in the language of the Accept-Language header", "properties": { "code": { "type": "string", "description": "Machine-readable key, e.g. spf.too_many_lookups" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ], "description": "Severity" }, "params": { "type": "object", "additionalProperties": true, "description": "Values of the finding, e.g. number of lookups" }, "message": { "type": "string", "description": "Translated description" }, "recommendation": { "type": [ "string", "null" ], "description": "Translated recommendation, if any" } }, "additionalProperties": true }, "Domain": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Domain ID" }, "name": { "type": "string", "description": "Domain in ASCII (punycode)" }, "unicode_name": { "type": "string", "description": "Domain in Unicode" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Customer ID" }, "customer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID" }, "name": { "type": "string", "description": "Name" } }, "description": "Assigned customer" }, "is_active": { "type": "boolean", "description": "Monitoring active" }, "paused_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Paused until" }, "is_paused": { "type": "boolean", "description": "Currently paused" }, "in_maintenance": { "type": "boolean", "description": "Currently inside an active maintenance window (no incidents or notifications)" }, "plan_paused": { "type": "boolean", "description": "Paused by the plan (above the domain limit)" }, "cms": { "type": [ "object", "null" ], "properties": { "key": { "type": "string", "description": "Key, e.g. wordpress" }, "name": { "type": "string", "description": "Name" }, "version": { "type": [ "string", "null" ], "description": "Detected version" } }, "description": "Detected content management system" }, "cms_detected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of CMS detection" }, "mail_detected": { "type": [ "boolean", "null" ], "description": "Whether the domain receives mail (MX present)" }, "monitoring_groups": { "type": "object", "properties": { "web": { "type": "boolean", "description": "Website and certificates" }, "mail": { "type": "boolean", "description": "Mail infrastructure" }, "dns": { "type": "boolean", "description": "DNS, DNSSEC, domain and blacklists" } }, "description": "Monitoring groups switched on or off" }, "notification_overrides": { "type": [ "object", "null" ], "description": "Notification rules for this domain only; null inherits the organization settings", "properties": { "failure_minutes": { "type": "integer", "description": "Minutes before a failure is reported (1 to 1440)", "minimum": 1, "maximum": 1440 }, "recovery_minutes": { "type": "integer", "description": "Minutes before recovery is reported (1 to 1440)", "minimum": 1, "maximum": 1440 }, "min_severity": { "type": "string", "enum": [ "info", "warning", "critical" ], "description": "Lowest severity that is reported" }, "ignore_quiet_hours": { "type": "boolean", "description": "Notify during quiet hours as well" }, "notify_on_change": { "type": "array", "items": { "type": "string" }, "description": "Change types that are reported" } } }, "health_status": { "type": "string", "enum": [ "healthy", "warning", "critical", "unknown" ], "description": "Overall health from all monitors" }, "health_computed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of computation" }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last check" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Domain expiry (registry), not available for .de" }, "expiry_available": { "type": "boolean", "description": "Whether an expiry date can be determined" }, "monitors": { "type": "array", "items": { "$ref": "#/components/schemas/Monitor" }, "description": "Monitors (only on single fetch, create and update)" }, "open_incidents_count": { "type": "integer", "description": "Open incidents" }, "suggestions_count": { "type": "integer", "description": "Open hostname suggestions (only on single fetch)" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Creation time" } } }, "HostnameSuggestion": { "type": "object", "description": "Hostname under a domain discovered in certificate transparency logs that is not monitored yet", "properties": { "id": { "type": "string", "format": "uuid", "description": "Suggestion ID" }, "domain_id": { "type": "string", "format": "uuid", "description": "Domain ID" }, "hostname": { "type": "string", "description": "Suggested hostname" }, "source": { "type": "string", "enum": [ "ct_log" ], "description": "Source of the suggestion" }, "status": { "type": "string", "enum": [ "new", "added", "dismissed" ], "description": "new (open), added (monitor created) or dismissed" }, "first_seen_at": { "type": "string", "format": "date-time", "description": "First seen" }, "last_seen_at": { "type": "string", "format": "date-time", "description": "Last seen" } } }, "DomainImport": { "type": "object", "description": "Background import of a confirmed domain list; the counters grow batch by batch until status is done or failed", "properties": { "id": { "type": "string", "format": "uuid", "description": "Import ID" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ], "description": "Queued, running, finished or aborted" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Customer for all created domains" }, "total": { "type": "integer", "description": "Names in the import (without blank lines, comments and duplicates)" }, "created": { "type": "integer", "description": "Created (new domains and hostnames of existing domains)" }, "skipped": { "type": "integer", "description": "Skipped: already monitored or present" }, "failed": { "type": "integer", "description": "Rejected, reason in errors" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Input" }, "reason": { "type": "string", "description": "Message" } } }, "description": "Rejected and skipped names with reason" }, "error": { "type": [ "string", "null" ], "description": "Reason when status is failed" }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Processing start" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Processing end" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Created at" } } }, "MaintenanceWindow": { "type": "object", "description": "Maintenance window: for one domain, one customer or the whole organization; no incidents or notifications are raised while it is active", "properties": { "id": { "type": "string", "format": "uuid", "description": "Maintenance window ID" }, "name": { "type": "string", "description": "Name" }, "kind": { "type": "string", "enum": [ "once", "weekly" ], "description": "One-off (starts_at to ends_at) or weekly (weekdays, time_from, time_to)" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Customer whose domains are affected; null for all" }, "customer_name": { "type": [ "string", "null" ], "description": "Customer name" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Single affected domain; null for all" }, "domain_name": { "type": [ "string", "null" ], "description": "Domain in Unicode" }, "starts_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Start (one-off)" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "End (one-off)" }, "weekdays": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "description": "Weekdays 1 (Monday) to 7 (Sunday), weekly" }, "time_from": { "type": [ "string", "null" ], "description": "Start HH:MM in the time zone of the window (weekly)" }, "time_to": { "type": [ "string", "null" ], "description": "End HH:MM; before time_from the window spans midnight" }, "timezone": { "type": "string", "description": "Time zone of the window" }, "is_enabled": { "type": "boolean", "description": "Enabled" }, "is_active": { "type": "boolean", "description": "Currently in effect" }, "is_expired": { "type": "boolean", "description": "One-off window whose end has passed" } } }, "Incident": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Incident ID" }, "domain_id": { "type": "string", "format": "uuid", "description": "Domain ID" }, "domain": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID" }, "name": { "type": "string", "description": "Domain" }, "unicode_name": { "type": "string", "description": "Domain in Unicode" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" } }, "description": "Affected domain" }, "monitor_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Monitor ID" }, "monitor": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID" }, "type": { "type": "string", "description": "Check type" }, "target": { "type": "string", "description": "Target" } }, "description": "Triggering monitor" }, "type": { "type": "string", "description": "Type, e.g. http.down, tls.expiring, spf.invalid" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ], "description": "Severity" }, "status": { "type": "string", "enum": [ "open", "acknowledged", "resolved" ], "description": "Status" }, "started_at": { "type": "string", "format": "date-time", "description": "Start" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Acknowledged at" }, "acknowledged_by": { "type": [ "string", "null" ], "description": "Name of the person who acknowledged" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Resolved at" }, "resolved_reason": { "type": [ "string", "null" ], "description": "Resolution reason, e.g. recovered, monitor_removed" }, "failure_count": { "type": "integer", "description": "Failed checks" }, "notification_count": { "type": "integer", "description": "Notifications sent" }, "reminder_count": { "type": "integer", "description": "Reminders sent" }, "cause": { "type": "object", "additionalProperties": true, "description": "Cause with findings (`findings`) and raw data" } } }, "Event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event ID" }, "type": { "type": "string", "description": "Type, e.g. dns.record_changed, tls.renewed, incident.opened" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ], "description": "Severity" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Domain ID" }, "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID" }, "name": { "type": "string", "description": "Domain" }, "unicode_name": { "type": "string", "description": "Domain in Unicode" } }, "description": "Affected domain" }, "monitor_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Monitor ID" }, "incident_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Related incident" }, "previous_value": { "description": "Value before the change (structure depends on the type)" }, "new_value": { "description": "Value after the change" }, "context": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Additional details" }, "occurred_at": { "type": "string", "format": "date-time", "description": "Time" } } }, "DnsSnapshot": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Snapshot ID" }, "fingerprint": { "type": "string", "description": "Fingerprint of all records" }, "source": { "type": "string", "description": "Query source" }, "resolver": { "type": [ "string", "null" ], "description": "Resolver used" }, "first_seen_at": { "type": "string", "format": "date-time", "description": "First seen" }, "last_seen_at": { "type": "string", "format": "date-time", "description": "Last confirmed" }, "previous_snapshot_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Previous snapshot" }, "records": { "type": "object", "additionalProperties": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "array", "prefixItems": [ { "type": "integer" }, { "type": "string" } ], "minItems": 2, "maxItems": 2, "description": "MX: [priority, host]" } ] } }, "description": "Records per type (A, AAAA, MX, NS, TXT, …); omitted in the snapshot list" }, "record_count": { "type": "integer", "description": "Total number of records" } } }, "CheckResult": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID" }, "checked_at": { "type": "string", "format": "date-time", "description": "Time" }, "status": { "type": "string", "enum": [ "ok", "warning", "critical", "error" ], "description": "Result; `error` when the check could not run (see `error_code`)" }, "latency_ms": { "type": [ "integer", "null" ], "description": "Response time in milliseconds" }, "http_status": { "type": [ "integer", "null" ], "description": "HTTP status (http only)" }, "error_code": { "type": [ "integer", "null" ], "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, null ], "description": "Reason for status error: 0 unknown, 1 resolver unavailable, 2 resolver timeout, 3 fetch unavailable, 4 target rejected by the guard, 5 timeout, 6 internal error, 7 outage disproved by the second location (not counted as downtime), 8 auxiliary probe from a second location (not counted towards availability), 9 domain does not exist (NXDOMAIN), 10 inconclusive (time budget: not all name servers were probed, no verdict)" }, "location": { "type": [ "string", "null" ], "description": "Check location, e.g. primary; null for older results" }, "payload": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Raw data" }, "findings": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Finding" }, "description": "Findings" } } }, "Uptime": { "type": "object", "properties": { "range": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ], "description": "Range" }, "source": { "type": "string", "enum": [ "raw", "check_result_hourly", "check_result_daily" ], "description": "Resolution: single checks (24h), hours (7d, 30d) or days (90d)" }, "summary": { "type": "object", "properties": { "uptime_ratio": { "type": [ "number", "null" ], "description": "Availability 0 to 1" }, "checks_total": { "type": "integer", "description": "Checks in the range" }, "latency_p50": { "type": [ "integer", "null" ], "description": "Median response time in ms" }, "latency_p95": { "type": [ "integer", "null" ], "description": "95th percentile response time in ms" }, "downtime_seconds": { "type": "integer", "description": "Downtime in seconds (not for 24h)" } } }, "points": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Data points: per check for 24h (t, status, latency_ms), otherwise per hour or day (t, uptime_ratio, latency_p50, latency_p95, checks_failed, downtime_seconds)" } } }, "Usage": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "key": { "type": "string", "description": "Plan key" }, "name": { "type": "string", "description": "Plan name" }, "domains": { "type": "integer", "description": "Domain limit" }, "hostnames_per_domain": { "type": "integer", "description": "Hostnames per domain" }, "retention_days": { "type": "integer", "description": "History in days" }, "members": { "type": "integer", "description": "Members" }, "channels": { "type": "integer", "description": "Channels" }, "min_interval": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Smallest check interval per check type in minutes" }, "sms_per_month": { "type": "integer", "description": "SMS per month" } }, "additionalProperties": true }, "domains": { "type": "integer", "description": "Domains" }, "monitors": { "type": "integer", "description": "Monitors" }, "members": { "type": "integer", "description": "Members" }, "channels": { "type": "integer", "description": "Channels" }, "checks_24h": { "type": "integer", "description": "Checks in the last 24 hours" } } }, "CustomerReport": { "type": "object", "description": "Monthly report; times are formatted for display (report language)", "properties": { "organization": { "type": "object", "properties": { "name": { "type": "string", "description": "Agency" } } }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "description": "Customer" }, "reference": { "type": [ "string", "null" ] } } }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "label": { "type": "string", "description": "Month as text" }, "month": { "type": "string", "description": "YYYY-MM" } } }, "generated_at": { "type": "string", "description": "Generated at (formatted)" }, "locale": { "type": "string", "description": "Report language" }, "summary": { "type": "object", "properties": { "domains": { "type": "integer" }, "healthy": { "type": "integer" }, "warning": { "type": "integer" }, "critical": { "type": "integer" }, "uptime": { "type": [ "number", "null" ], "description": "Availability in percent" }, "incidents": { "type": "integer" }, "critical_incidents": { "type": "integer" }, "changes": { "type": "integer" }, "downtime_minutes": { "type": "integer" } } }, "domains": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Domain" }, "health": { "type": "string", "enum": [ "healthy", "warning", "critical", "unknown" ] }, "uptime": { "type": [ "number", "null" ] }, "downtime_minutes": { "type": "integer" }, "incidents": { "type": "integer" }, "critical_incidents": { "type": "integer" }, "certificate_valid_to": { "type": [ "string", "null" ] }, "certificate_days_left": { "type": [ "integer", "null" ] }, "certificate_issuer": { "type": [ "string", "null" ] }, "domain_expires_at": { "type": [ "string", "null" ], "format": "date" }, "registrar": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "incidents": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain" }, "type": { "type": "string", "description": "Incident type" }, "label": { "type": "string", "description": "Label" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "started_at": { "type": "string", "description": "Start (formatted)" }, "resolved_at": { "type": [ "string", "null" ] }, "duration_minutes": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "open", "acknowledged", "resolved" ] } } } }, "changes": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": [ "string", "null" ] }, "type": { "type": "string", "description": "Event type" }, "label": { "type": "string", "description": "Label" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "occurred_at": { "type": "string", "description": "Time (formatted)" }, "previous": { "type": [ "string", "null" ] }, "new": { "type": [ "string", "null" ] } } } }, "expiring_certificates": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Certificates expiring soon" }, "expiring_domains": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Domains expiring soon" } }, "additionalProperties": true }, "Dashboard": { "type": "object", "properties": { "domains": { "type": "object", "properties": { "total": { "type": "integer", "description": "All domains" }, "healthy": { "type": "integer", "description": "Healthy" }, "warning": { "type": "integer", "description": "Warning" }, "critical": { "type": "integer", "description": "Critical" }, "unknown": { "type": "integer", "description": "Not checked yet" } } }, "needs_attention": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" }, "description": "Open incidents, critical first (at most 50)" }, "recent_changes": { "type": "array", "items": { "$ref": "#/components/schemas/Event" }, "description": "Detected changes of the last 24 hours (at most 30)" }, "usage": { "type": "object", "properties": { "domains": { "type": "integer", "description": "Domains in use" }, "domains_limit": { "type": "integer", "description": "Domain limit of the plan" }, "plan": { "type": "string", "description": "Plan key" }, "plan_name": { "type": "string", "description": "Plan name" } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "incidents": { "type": "integer" }, "changes": { "type": "integer" }, "checks_failed": { "type": "integer" }, "checks_total": { "type": "integer" } } }, "description": "Last 14 days, one entry per day" }, "generated_at": { "type": "string", "format": "date-time", "description": "Generated at (cached for up to 30 seconds, ETag is set)" } } }, "PageMeta": { "type": "object", "description": "Page-based pagination", "properties": { "current_page": { "type": "integer" }, "from": { "type": [ "integer", "null" ] }, "to": { "type": [ "integer", "null" ] }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "path": { "type": "string" } } }, "CursorMeta": { "type": "object", "description": "Cursor pagination: pass `next_cursor` as the `cursor` parameter of the next request, null at the end", "properties": { "path": { "type": "string" }, "per_page": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } } }, "Links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } } }, "ProblemDetails": { "type": "object", "description": "Error according to RFC 9457 (Content-Type application/problem+json)", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Error type, e.g. https://domainwarn.com/errors/not-found" }, "title": { "type": "string", "description": "Short title" }, "status": { "type": "integer", "description": "HTTP status" }, "detail": { "type": "string", "description": "Explanation" } } }, "PlanProblem": { "allOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "type": "object", "properties": { "plan": { "type": "string", "description": "Effective plan" }, "suspended": { "type": "boolean", "description": "Suspended by the operator" } } } ] }, "ValidationProblem": { "allOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "type": "object", "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Messages per field" } } } ] } } } }