{
  "openapi": "3.1.0",
  "info": {
    "title": "Cnamio API",
    "version": "1.0.0",
    "summary": "Connect your users' custom domains to your product.",
    "description": "Cnamio finds where a domain's DNS is hosted, creates the DNS records your product needs (with a provider API token the end user pastes, used once and never stored) or returns the exact records to copy, confirms them on the domain's authoritative nameservers and notifies your backend with a signed webhook. Existing DNS records are never changed or deleted.\n\nFlow: your server calls POST /token with the application secret; the session token is then used (from your server or from the browser) on the session routes. Management routes use HTTP Basic with applicationId:secret and are server-only.\n\nAgent guide: https://cnamio.com/agent-onboarding/SKILL.md · Docs: https://cnamio.com/docs.md",
    "contact": { "name": "Cnamio", "email": "contato@cnamio.com", "url": "https://cnamio.com" },
    "termsOfService": "https://cnamio.com/terms",
    "license": { "name": "Proprietary", "url": "https://cnamio.com/terms" }
  },
  "servers": [{ "url": "https://api.cnamio.com" }],
  "externalDocs": { "description": "Developer docs (Markdown)", "url": "https://cnamio.com/docs.md" },
  "tags": [
    { "name": "Session", "description": "Create a 60-minute session token on your server." },
    { "name": "Connections", "description": "Check a domain, connect it and follow propagation. Bearer session token + applicationId header. These routes answer CORS." },
    { "name": "Public", "description": "No credentials. Read-only, tightly rate limited, no CORS." },
    { "name": "Management", "description": "Server-only routes with HTTP Basic (applicationId:secret). No CORS." },
    { "name": "Public site", "description": "Anonymous, read-only routes behind the demo and the free checker on cnamio.com. Same origin only (no CORS), tight limits per address." }
  ],
  "paths": {
    "/token": {
      "post": {
        "tags": ["Session"],
        "operationId": "createSessionToken",
        "summary": "Create a session token",
        "description": "Call from your server only (never answers CORS). Optional domain, userId and dnsRecords bind the session to exactly those values.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["applicationId", "secret"],
            "properties": {
              "applicationId": { "type": "string", "pattern": "^app_", "example": "app_XXXXXXXXXXXXXXXX" },
              "secret": { "type": "string", "pattern": "^cnm_sk_", "description": "Application secret. Keep it on the server." },
              "domain": { "type": "string", "description": "Optional: the session may only be used for this domain." },
              "userId": { "type": "string", "maxLength": 128, "description": "Optional: your user's id; echoed in jobs and webhooks." },
              "dnsRecords": { "$ref": "#/components/schemas/DnsRecords" }
            } } } }
        },
        "responses": {
          "200": { "description": "Session created", "content": { "application/json": { "schema": {
            "type": "object", "required": ["auth_token"], "properties": { "auth_token": { "type": "string", "description": "Valid for 60 minutes." } } } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/checkdomain": {
      "post": {
        "tags": ["Connections"],
        "operationId": "checkDomain",
        "summary": "Detect the DNS provider and how the domain can be connected",
        "description": "Read-only. For a single required CNAME at the domain it also returns recordState (read from the authoritative nameservers) and, with locale pt/pt-BR, provider step-by-step instructions.",
        "security": [{ "session": [], "applicationId": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object", "required": ["domain"],
          "properties": {
            "domain": { "type": "string", "example": "shop.example.com" },
            "dnsRecords": { "$ref": "#/components/schemas/DnsRecords" },
            "checkConflicts": { "type": "boolean", "description": "Also report records already published that would block the connection." },
            "acceptMerges": { "type": "boolean", "description": "The caller understands recordMerges: an SPF policy that will be merged into the existing one is reported there only. Without it, each merge is also a recordConflicts entry with reason spf_merge_required and the merged value in merge." },
            "locale": { "type": "string", "example": "pt-BR" }
          } } } } },
        "responses": {
          "200": { "description": "Domain analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckDomain" } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Busy" }
        }
      }
    },
    "/v1/lookup": {
      "get": {
        "tags": ["Public"],
        "operationId": "lookupDomain",
        "summary": "Which DNS provider serves a domain, and whether setup there is automatic or guided",
        "description": "Anonymous and read-only: the live demo on cnamio.com. It reads the domain's nameservers and nothing else (no records, no conflict check), stores nothing and never answers CORS. Limited to a few requests per minute per address. `mode` is `automatic` only for providers Cnamio announces as automatic; whether one application can use it is told by POST /checkdomain, which is the route to build on.",
        "security": [],
        "parameters": [{ "name": "domain", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 253 }, "example": "shop.example.com" }],
        "responses": {
          "200": { "description": "Where the DNS is hosted", "content": { "application/json": { "schema": {
            "type": "object", "required": ["domain", "zone", "provider", "providerName", "mode", "nameservers"],
            "properties": {
              "domain": { "type": "string", "example": "shop.example.com" },
              "zone": { "type": "string", "example": "example.com" },
              "provider": { "type": "string", "description": "Provider id, or `other` when the nameservers are not recognized.", "example": "cloudflare" },
              "providerName": { "type": ["string", "null"], "description": "Display name; null when the provider is not recognized.", "example": "Cloudflare" },
              "mode": { "enum": ["automatic", "guided"] },
              "nameservers": { "type": "array", "items": { "type": "string" } }
            } } } } },
          "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "405": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Busy" }
        }
      }
    },
    "/connect": {
      "post": {
        "tags": ["Connections"],
        "operationId": "connectManual",
        "summary": "Manual setup: get the exact records and start watching propagation",
        "security": [{ "session": [], "applicationId": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object", "required": ["domain"],
          "properties": { "domain": { "type": "string" }, "dnsRecords": { "$ref": "#/components/schemas/DnsRecords" }, "userId": { "type": "string" }, "locale": { "type": "string" } } } } } },
        "responses": {
          "201": { "description": "Connection started", "content": { "application/json": { "schema": {
            "type": "object", "required": ["job_id", "status", "domain", "records"],
            "properties": {
              "job_id": { "$ref": "#/components/schemas/JobId" }, "status": { "$ref": "#/components/schemas/JobStatus" },
              "domain": { "type": "string" }, "zone": { "type": "string" }, "provider": { "type": "string" }, "setup_type": { "const": "manual" },
              "records": { "type": "array", "items": { "$ref": "#/components/schemas/PlannedRecord" } },
              "recordMerges": { "type": "array", "description": "Present when an SPF record was asked for where a policy is already published: the full merged policy to set on the existing record (value) and the policy it replaces. Also on that record as merge.",
                "items": { "type": "object", "properties": { "type": { "const": "TXT" }, "host": { "type": "string" }, "value": { "type": "string" }, "replaces": { "type": "string" }, "requested": { "type": "string" } } } },
              "instructions": { "$ref": "#/components/schemas/Instructions" }
            } } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/QuotaReached" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Busy" }
        }
      }
    },
    "/connect/automatic": {
      "post": {
        "tags": ["Connections"],
        "operationId": "connectAutomatic",
        "summary": "Create the records with the end user's DNS provider API token (used once, never stored)",
        "description": "Available when /checkdomain returns connectMethods containing api_token. Never deletes existing records; the only existing record it can change is an SPF policy, extended with the requested mechanisms while every existing term is kept (only where the operator enabled it for the DNS provider; otherwise 409 spf_merge_required).",
        "security": [{ "session": [], "applicationId": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object", "required": ["domain", "providerToken"],
          "properties": {
            "domain": { "type": "string" }, "dnsRecords": { "$ref": "#/components/schemas/DnsRecords" },
            "providerToken": { "type": "string", "description": "The end user's API token for their DNS provider. Used during this request only." },
            "provider": { "type": "string", "description": "Optional; must match the detected provider." },
            "userId": { "type": "string" }
          } } } } },
        "responses": {
          "201": { "description": "Records created (or already present); propagation is now watched", "content": { "application/json": { "schema": {
            "type": "object", "required": ["job_id", "status", "domain", "provider"],
            "properties": {
              "job_id": { "$ref": "#/components/schemas/JobId" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "domain": { "type": "string" },
              "provider": { "type": "string" }, "setup_type": { "const": "automatic" }, "written": { "type": "boolean" },
              "warning": { "const": "zone_changed", "description": "The records were written, but the zone or its delegation changed during the write; the job still tracks propagation" },
              "failed_optional_records": { "type": "array", "items": { "type": "object" } }
            } } } } },
          "409": { "description": "Existing records block the connection (or the zone changed before the write); none of the requested records was written", "content": { "application/json": { "schema": {
            "type": "object", "properties": { "message": { "type": "string" }, "conflicts": { "type": "array", "items": { "type": "string" } } } } } } },
          "422": { "$ref": "#/components/responses/Error" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/QuotaReached" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Busy" }
        }
      }
    },
    "/connect/{jobId}/status": {
      "get": {
        "tags": ["Connections"],
        "operationId": "getConnectionStatus",
        "summary": "Status of a connection",
        "security": [{ "session": [], "applicationId": [] }],
        "parameters": [{ "$ref": "#/components/parameters/JobId" }],
        "responses": {
          "200": { "description": "Status", "content": { "application/json": { "schema": {
            "type": "object", "properties": {
              "job_id": { "$ref": "#/components/schemas/JobId" }, "connected": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/JobStatus" },
              "domain": { "type": "string" }, "propagation_status": { "enum": ["pending", "success", "failed"] }, "setup_type": { "enum": ["automatic", "manual"] },
              "health": { "$ref": "#/components/schemas/Health" }, "monitored": { "type": "boolean", "description": "This connection is being monitored now." },
              "health_changed_at": { "type": ["string", "null"], "format": "date-time" }, "health_checked_at": { "type": ["string", "null"], "format": "date-time" },
              "missing_records": { "$ref": "#/components/schemas/MissingRecords" },
              "share_link_id": { "type": ["string", "null"], "description": "The shareable link this connection was started from" } } } } } },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/connect/propagation/recheck/{jobId}": {
      "post": {
        "tags": ["Connections"],
        "operationId": "recheckPropagation",
        "summary": "Check propagation again now (at most once every 5 minutes)",
        "description": "Only for connections still in progress. A connection that already reached completed or failed answers 409 and nothing is checked (this 409 has no conflicts list: it is not a DNS conflict).",
        "security": [{ "session": [], "applicationId": [] }],
        "parameters": [{ "$ref": "#/components/parameters/JobId" }],
        "responses": {
          "202": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "const": true } } } } } },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "description": "The connection is already finished (completed or failed); nothing is checked again", "content": { "application/json": { "schema": {
            "type": "object", "properties": { "message": { "type": "string" } } } } } },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/connect/webhooks/last/{jobId}": {
      "get": {
        "tags": ["Connections"],
        "operationId": "getLastWebhook",
        "summary": "Last webhook of a connection and its delivery state",
        "security": [{ "session": [], "applicationId": [] }],
        "parameters": [{ "$ref": "#/components/parameters/JobId" }],
        "responses": {
          "200": { "description": "Last webhook", "content": { "application/json": { "schema": {
            "type": "object", "properties": {
              "event_id": { "type": "string" }, "type": { "type": "string" }, "payload": { "$ref": "#/components/schemas/WebhookEvent" },
              "attempts": { "type": "integer" }, "delivered": { "type": "boolean" }, "last_status": { "type": ["integer", "null"] }, "created_at": { "type": "string", "format": "date-time" } } } } } },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/demo": {
      "get": {
        "tags": [
          "Public site"
        ],
        "operationId": "publicDemo",
        "summary": "Live demo of cnamio.com (anonymous, read-only)",
        "security": [],
        "description": "For the public demo page of this same origin (no CORS answer). Reads the DNS provider and nameservers of a domain, plans the records of a sample app (a CNAME at the name and an ownership TXT under it; a root domain is shown as its www), reads what the zone's own nameservers publish at those names and returns the conflicts, the connect methods that would be offered, and the domain.added webhook body the app's backend would receive. Nothing is written, stored or logged about the name. Limits: 6 requests per minute per address and a shared ceiling for all addresses; 8 s of DNS.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 253
            }
          }
        ],
        "responses": {
          "200": {
            "description": "What a customer would see",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "type": "string"
                    },
                    "hostname": {
                      "type": "string",
                      "description": "The name the sample app connects."
                    },
                    "usedWww": {
                      "type": "boolean"
                    },
                    "zone": {
                      "type": "string"
                    },
                    "provider": {
                      "type": "string"
                    },
                    "providerName": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "mode": {
                      "enum": [
                        "automatic",
                        "guided"
                      ]
                    },
                    "nameservers": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "connectMethods": {
                      "type": "array",
                      "items": {
                        "enum": [
                          "domain_connect",
                          "api_token",
                          "manual"
                        ]
                      }
                    },
                    "outcome": {
                      "enum": [
                        "ready",
                        "conflict",
                        "unknown"
                      ]
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string"
                          },
                          "host": {
                            "type": "string"
                          },
                          "value": {
                            "type": "string"
                          },
                          "ttl": {
                            "type": "integer"
                          },
                          "optional": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "conflicts": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "description": "Null: the existing records could not be read (never treated as free).",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string"
                          },
                          "host": {
                            "type": "string"
                          },
                          "reason": {
                            "type": "string"
                          },
                          "existing": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string"
                                },
                                "value": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "webhook": {
                      "type": "object",
                      "properties": {
                        "headers": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "body": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "405": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/v1/tools/record": {
      "get": {
        "tags": [
          "Public site"
        ],
        "operationId": "publicRecordCheck",
        "summary": "Free record checker of cnamio.com (anonymous, read-only)",
        "security": [],
        "description": "For the public checker page of this same origin (no CORS answer). What the zone's authoritative nameservers publish at one name and type (not a resolver's cache), the zone and its provider, and whether an expected value is there. Limits: 10 requests per minute per address and a shared ceiling; 8 s of DNS.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 253
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "enum": [
                "CNAME",
                "A",
                "AAAA",
                "TXT",
                "MX",
                "CAA"
              ],
              "default": "CNAME"
            }
          },
          {
            "name": "expected",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 512
            },
            "description": "MX as \"priority host\"."
          }
        ],
        "responses": {
          "200": {
            "description": "Published values",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "zone": {
                      "type": "string"
                    },
                    "provider": {
                      "type": "string"
                    },
                    "providerName": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "nameservers": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "source": {
                      "const": "authoritative"
                    },
                    "values": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "expected": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "matches": {
                      "type": [
                        "boolean",
                        "null"
                      ]
                    },
                    "others": {
                      "type": "array",
                      "description": "For an empty CNAME: the addresses published at the name instead.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string"
                          },
                          "value": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "hints": {
                      "type": "array",
                      "items": {
                        "enum": [
                          "cloudflare_proxied",
                          "apex_cname"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "405": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/v1/manage/application": {
      "get": {
        "tags": ["Management"], "operationId": "getApplication", "summary": "Application settings", "security": [{ "basic": [] }],
        "responses": { "200": { "description": "Application", "content": { "application/json": { "schema": { "type": "object", "properties": {
          "application_id": { "type": "string" }, "name": { "type": "string" }, "webhook_url": { "type": ["string", "null"] },
          "compat": { "type": ["string", "null"] }, "live_providers": { "type": "array", "items": { "type": "string" } },
          "domain_connect_service": { "type": ["string", "null"] },
          "strict_names": { "type": "boolean", "description": "Record names must be the connected hostname, a name under it, or one of allowed_names." },
          "allowed_names": { "type": "array", "items": { "type": "string" }, "description": "Extra names, relative to the zone (@ is the zone itself)." },
          "monitoring": { "type": "boolean", "description": "Continuous monitoring of connected domains is on." },
          "monitor_limit": { "type": "integer", "description": "Cap of monitored domains of this application." },
          "monitored_domains": { "type": "integer", "description": "Domains being monitored now." },
          "mode": { "enum": ["live", "test"], "description": "test: every connection goes to the sandbox provider and no real DNS is read or written." },
          "plan": { "type": ["string", "null"], "enum": ["free", "starter", "growth", null], "description": "Monthly connection plan of a live application; null: no plan quota." },
          "quota": { "$ref": "#/components/schemas/Quota" } } } } } }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/manage/monitoring": {
      "put": {
        "tags": ["Management"], "operationId": "setMonitoring", "summary": "Turn continuous monitoring of connected domains on or off (read-only DNS checks)", "security": [{ "basic": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["enabled"], "properties": { "enabled": { "type": "boolean" } } } } } },
        "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": {
          "monitoring": { "type": "boolean" }, "monitor_limit": { "type": "integer" }, "monitored_domains": { "type": "integer" } } } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/manage/record-names": {
      "put": {
        "tags": ["Management"], "operationId": "setRecordNames", "summary": "Strict record names and the extra names accepted outside the connected hostname", "security": [{ "basic": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {
          "strict": { "type": "boolean" }, "allowedNames": { "type": "array", "maxItems": 50, "items": { "type": "string", "example": "_dmarc" } } } } } } },
        "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": {
          "strict_names": { "type": "boolean" }, "allowed_names": { "type": "array", "items": { "type": "string" } } } } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/manage/webhook": {
      "put": {
        "tags": ["Management"], "operationId": "setWebhookUrl", "summary": "Set (HTTPS, public) or clear the webhook URL", "security": [{ "basic": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url"],
          "properties": { "url": { "type": ["string", "null"], "format": "uri" } } } } } },
        "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": ["string", "null"] } } } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/manage/webhook-secret": {
      "get": {
        "tags": ["Management"], "operationId": "getWebhookSecret", "summary": "The secret that signs your webhooks", "security": [{ "basic": [] }],
        "responses": { "200": { "description": "Secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_secret": { "type": "string" } } } } } },
          "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/manage/webhook-test": {
      "post": {
        "tags": ["Management"], "operationId": "sendTestWebhook", "summary": "Send a signed webhook.test event to your URL", "security": [{ "basic": [] }],
        "responses": { "200": { "description": "Delivery result", "content": { "application/json": { "schema": { "type": "object", "properties": {
          "delivered": { "type": "boolean" }, "status": { "type": ["integer", "null"] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/manage/rotate-secret": {
      "post": {
        "tags": ["Management"], "operationId": "rotateSecret", "summary": "New application secret; the old one keeps working for the grace period", "security": [{ "basic": [] }],
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "graceHours": { "type": "number", "minimum": 0, "maximum": 168, "default": 24 } } } } } },
        "responses": { "200": { "description": "New secret (shown once)", "content": { "application/json": { "schema": { "type": "object", "properties": {
          "application_id": { "type": "string" }, "secret": { "type": "string" }, "previous_valid_until": { "type": "string", "format": "date-time" } } } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/manage/jobs": {
      "get": {
        "tags": ["Management"], "operationId": "listConnections", "summary": "Recent connections, newest first", "security": [{ "basic": [] }],
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } },
          { "name": "before", "in": "query", "description": "next_before of the previous page", "schema": { "type": "string", "format": "date-time" } },
          { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/JobStatus" } },
          { "name": "domain", "in": "query", "description": "Only this domain's connections", "schema": { "type": "string" } },
          { "name": "health", "in": "query", "description": "Only connections in this monitoring state", "schema": { "enum": ["healthy", "degraded", "broken"] } },
          { "name": "share_link_id", "in": "query", "description": "Only connections started from this shareable link", "schema": { "type": "string", "pattern": "^shl_[A-Za-z0-9_-]{16}$" } }
        ],
        "responses": { "200": { "description": "Page of connections", "content": { "application/json": { "schema": { "type": "object", "properties": {
          "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "next_before": { "type": ["string", "null"], "format": "date-time" } } } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/manage/share-links": {
      "post": {
        "tags": ["Management"], "operationId": "createShareLink", "summary": "A link for whoever manages the DNS (agency, IT team): they connect these domains with these records without your secret", "security": [{ "basic": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["domains", "dnsRecords"], "properties": {
          "domains": { "type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "example": "shop.customer.com" } },
          "dnsRecords": { "$ref": "#/components/schemas/DnsRecords" },
          "maxUses": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1, "description": "Connections each domain may start through the link" },
          "expiresInDays": { "type": "number", "minimum": 0.042, "maximum": 30, "default": 7 },
          "userId": { "type": "string", "maxLength": 128, "description": "Echoed as user_id in the connections and webhooks" },
          "label": { "type": "string", "maxLength": 120, "description": "Your own note; never shown on the link page" } } } } } },
        "responses": { "201": { "description": "Created. `url` and `token` are returned only here.", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/ShareLink" },
          { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://api.cnamio.com/s/cnsl_…" }, "token": { "type": "string", "pattern": "^cnsl_[A-Za-z0-9_-]{43}$" } } }] } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" } }
      },
      "get": {
        "tags": ["Management"], "operationId": "listShareLinks", "summary": "Shareable links, newest first (never their tokens)", "security": [{ "basic": [] }],
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } },
          { "name": "before", "in": "query", "description": "next_before of the previous page", "schema": { "type": "string", "format": "date-time" } }
        ],
        "responses": { "200": { "description": "Page of links", "content": { "application/json": { "schema": { "type": "object", "properties": {
          "share_links": { "type": "array", "items": { "$ref": "#/components/schemas/ShareLink" } }, "next_before": { "type": ["string", "null"], "format": "date-time" } } } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/manage/share-links/{shareLinkId}": {
      "get": {
        "tags": ["Management"], "operationId": "getShareLink", "summary": "One shareable link", "security": [{ "basic": [] }],
        "parameters": [{ "name": "shareLinkId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^shl_[A-Za-z0-9_-]{16}$" } }],
        "responses": { "200": { "description": "The link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLink" } } } },
          "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/manage/share-links/{shareLinkId}/revoke": {
      "post": {
        "tags": ["Management"], "operationId": "revokeShareLink", "summary": "End a shareable link now (connections already started go on)", "security": [{ "basic": [] }],
        "parameters": [{ "name": "shareLinkId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^shl_[A-Za-z0-9_-]{16}$" } }],
        "responses": { "200": { "description": "Revoked (idempotent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLink" } } } },
          "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/manage/usage": {
      "get": {
        "tags": ["Management"], "operationId": "getUsage", "summary": "Monthly usage (UTC calendar month)", "security": [{ "basic": [] }],
        "parameters": [{ "name": "month", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-11" } }],
        "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "type": "object", "properties": {
          "month": { "type": "string" }, "started": { "type": "object", "properties": { "automatic": { "type": "integer" }, "manual": { "type": "integer" } } },
          "connected": { "type": "integer" }, "billable_domains": { "type": "integer", "description": "Each connected domain counts once per month." },
          "timed_out": { "type": "integer" }, "complete": { "type": "boolean" }, "quota": { "$ref": "#/components/schemas/Quota" } } } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    }
  },
  "webhooks": {
    "domainEvent": {
      "post": {
        "operationId": "receiveDomainEvent",
        "summary": "domain.added, domain.propagation.timeout, domain.records_missing, domain.records_restored and webhook.test, sent to your webhook URL",
        "security": [],
        "description": "Headers: Cnamio-Timestamp (unix seconds), Cnamio-Event-Id, Cnamio-Signature: sha256=<hex HMAC-SHA256 of \"{timestamp}.{raw body}\" with your webhook secret>. Reject timestamps older than 5 minutes. Retries after 1, 5 and 30 minutes; redirects are not followed.",
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } },
        "responses": { "200": { "description": "Any 2xx acknowledges the event." } }
      }
    },
    "usageQuotaWarning": {
      "post": {
        "operationId": "receiveUsageQuotaWarning",
        "summary": "usage.quota_warning: 80% of the plan's monthly connections used (once per UTC month)",
        "security": [],
        "description": "Same headers and signature as the domain events. Sent once per month to a live application on a plan, queued on the connection whose start crossed the threshold.",
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {
          "id": { "type": "string" }, "type": { "const": "usage.quota_warning" }, "application_id": { "type": "string" }, "job_id": { "type": "string" },
          "plan": { "type": "string" }, "month": { "type": "string", "example": "2026-11" }, "limit": { "type": "integer" }, "used": { "type": "integer" },
          "remaining": { "type": "integer" }, "threshold": { "type": "number" }, "resets_at": { "type": "string", "format": "date-time" },
          "created_at": { "type": "string", "format": "date-time" } } } } } },
        "responses": { "200": { "description": "Any 2xx acknowledges the event." } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "session": { "type": "http", "scheme": "bearer", "description": "auth_token from POST /token" },
      "applicationId": { "type": "apiKey", "in": "header", "name": "applicationId" },
      "basic": { "type": "http", "scheme": "basic", "description": "applicationId:secret" }
    },
    "parameters": { "JobId": { "name": "jobId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/JobId" } } },
    "responses": {
      "Busy": {
        "description": "Not now: the DNS reads of this request ran out of time, or too many requests are reading DNS. Nothing was written and no connection was started; repeat the same request after Retry-After seconds.",
        "headers": { "Retry-After": { "description": "Seconds to wait before repeating the request.", "schema": { "type": "integer" } } },
        "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } }
      }, "Error": { "description": "Error with a fixed message (request contents are never echoed)", "content": { "application/json": { "schema": {
      "type": "object", "properties": { "message": { "type": "string" } } } } } },
      "QuotaReached": {
        "description": "The plan of this live application has no connections left this month. Domains already connected keep working; nothing was started. A test application over its sandbox cap gets the same body with 429 and code sandbox_limit_reached.",
        "headers": { "Retry-After": { "description": "Seconds until the UTC month turns and the count starts over.", "schema": { "type": "integer" } } },
        "content": { "application/json": { "schema": { "type": "object", "properties": {
          "message": { "type": "string" }, "code": { "enum": ["plan_limit_reached", "sandbox_limit_reached"] }, "plan": { "type": ["string", "null"] },
          "limit": { "type": "integer" }, "used": { "type": "integer" }, "resets_at": { "type": "string", "format": "date-time" } } } } }
      } },
    "schemas": {
      "JobId": { "type": "string", "pattern": "^job_[0-9a-f-]{36}$" },
      "JobStatus": { "enum": ["pending", "in_progress", "completed", "failed"] },
      "Quota": { "type": ["object", "null"], "description": "The monthly cap that applies (the plan of a live application, or the sandbox cap of a test one); null when none applies.",
        "properties": { "kind": { "enum": ["plan", "sandbox"] }, "plan": { "type": ["string", "null"] }, "limit": { "type": "integer" },
          "used": { "type": "integer", "description": "Distinct domains whose connection started this UTC month and did not time out." },
          "remaining": { "type": "integer" }, "resets_at": { "type": "string", "format": "date-time" } } },
      "Health": { "enum": ["healthy", "degraded", "broken", null], "description": "Continuous monitoring of a connected domain. healthy: every record is where it was. degraded: the required records are there, but an optional record that was published is gone, or the zone could not be read for several checks in a row. broken: a required record is gone. null: not monitored." },
      "MissingRecords": { "type": "array", "description": "Records published when the connection completed and not found by the last monitoring check (empty while healthy).", "items": { "type": "object", "properties": {
        "type": { "type": "string" }, "host": { "type": "string" }, "value": { "type": "string" }, "optional": { "type": "boolean" } } } },
      "DnsRecord": {
        "type": "object", "required": ["type", "host", "value"],
        "properties": {
          "type": { "enum": ["A", "AAAA", "CNAME", "TXT", "MX", "CAA"] },
          "host": { "type": "string", "description": "Relative to the zone; placeholders {DOMAIN}, {SUBDOMAIN}, {SLD}, {TLD}; @ is the apex.", "example": "{SUBDOMAIN}" },
          "value": { "type": "string", "example": "app.yourproduct.com" },
          "ttl": { "type": "integer", "default": 300 },
          "priority": { "type": "integer", "description": "MX only" },
          "optional": { "type": "boolean", "default": false }
        }
      },
      "DnsRecords": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/DnsRecord" } },
      "Instructions": {
        "type": "object", "description": "Step-by-step in the user's DNS provider panel (Portuguese guides today).",
        "properties": { "language": { "type": "string" }, "provider": { "type": "string" }, "providerName": { "type": "string" }, "title": { "type": "string" },
          "steps": { "type": "array", "items": { "type": "string" } }, "verification": { "type": "string" },
          "record": { "type": "object", "properties": { "type": { "type": "string" }, "host": { "type": "string" }, "value": { "type": "string" } } } }
      },
      "PlannedRecord": {
        "type": "object", "description": "A record as it would be created: full name, canonical value.",
        "properties": { "type": { "type": "string" }, "host": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": "integer" }, "optional": { "type": "boolean" },
          "merge": { "type": "object", "description": "POST /connect only, on an SPF record asked for where a policy is already published: edit that policy to value (it replaces replaces); never add a second SPF record.",
            "properties": { "value": { "type": "string" }, "replaces": { "type": "string" } } } }
      },
      "CheckDomain": {
        "type": "object",
        "properties": {
          "domain": { "type": "string" }, "zone": { "type": "string" }, "provider": { "type": "string", "description": "Detected from the nameservers; 'other' when unknown." },
          "setupType": { "enum": ["Automatic", "Manual"] }, "authoritativeDnsProvider": { "type": "string" },
          "nameservers": { "type": "array", "items": { "type": "string" } },
          "connectMethods": { "type": "array", "items": { "enum": ["api_token", "domain_connect"] } },
          "sandbox": { "const": true, "description": "Present only for test applications: the provider is the sandbox and no real DNS is read or written." },
          "domainConnect": { "type": "object", "description": "Present when connectMethods contains domain_connect: the provider whose consent page the connect window opens.",
            "properties": { "provider": { "type": "string" }, "providerName": { "type": "string" } } },
          "records": { "type": "array", "description": "Every record that would be created, with its full name.", "items": { "$ref": "#/components/schemas/PlannedRecord" } },
          "recordState": { "enum": ["missing", "configured", "different_cname", "name_occupied", "inconclusive"] },
          "recordConflicts": { "type": ["array", "null"], "items": { "type": "object", "properties": {
            "type": { "type": "string" }, "host": { "type": "string" }, "value": { "type": "string" }, "reason": { "type": "string" },
            "existing": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" } } } },
            "merge": { "type": "object", "description": "Only with reason spf_merge_required: the full policy to publish instead (every existing term kept) and the policy it replaces.",
              "properties": { "value": { "type": "string" }, "replaces": { "type": "string" } } } } } },
          "recordMerges": { "type": "array", "description": "Present (with checkConflicts) when a requested SPF policy will be merged into the one already published: value is the full merged policy, which keeps every existing term; replaces is the policy it replaces.",
            "items": { "type": "object", "properties": { "type": { "const": "TXT" }, "host": { "type": "string" }, "value": { "type": "string" }, "replaces": { "type": "string" }, "requested": { "type": "string" } } } },
          "instructions": { "$ref": "#/components/schemas/Instructions" }
        }
      },
      "Job": {
        "type": "object",
        "properties": {
          "job_id": { "$ref": "#/components/schemas/JobId" }, "domain": { "type": "string" }, "user_id": { "type": ["string", "null"] }, "provider": { "type": ["string", "null"] },
          "setup_type": { "enum": ["automatic", "manual"] }, "status": { "$ref": "#/components/schemas/JobStatus" },
          "propagation_status": { "enum": ["pending", "success", "failed"] }, "created_at": { "type": "string", "format": "date-time" },
          "completed_at": { "type": ["string", "null"], "format": "date-time" },
          "health": { "$ref": "#/components/schemas/Health" }, "monitored": { "type": "boolean", "description": "This connection is being monitored now." },
          "health_changed_at": { "type": ["string", "null"], "format": "date-time" }, "health_checked_at": { "type": ["string", "null"], "format": "date-time" },
          "missing_records": { "$ref": "#/components/schemas/MissingRecords" },
          "share_link_id": { "type": ["string", "null"], "description": "The shareable link this connection was started from" }
        }
      },
      "ShareLink": {
        "type": "object",
        "properties": {
          "share_link_id": { "type": "string", "pattern": "^shl_[A-Za-z0-9_-]{16}$" },
          "status": { "enum": ["active", "expired", "revoked", "used"], "description": "used: every domain spent its uses" },
          "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "uses": { "type": "integer" }, "uses_left": { "type": "integer" } } } },
          "dns_records": { "$ref": "#/components/schemas/DnsRecords" }, "user_id": { "type": ["string", "null"] }, "label": { "type": ["string", "null"] },
          "max_uses": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" },
          "revoked_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "WebhookEvent": {
        "type": "object",
        "properties": {
          "id": { "type": "string" }, "type": { "enum": ["domain.added", "domain.propagation.timeout", "domain.records_missing", "domain.records_restored", "webhook.test"] },
          "job_id": { "$ref": "#/components/schemas/JobId" }, "user_id": { "type": ["string", "null"] }, "domain": { "type": "string" }, "subdomain": { "type": "string" },
          "provider": { "type": "string" }, "setup_type": { "enum": ["automatic", "manual"] }, "propagation_status": { "enum": ["pending", "success", "failed"] },
          "optional_records_propagation_status": { "enum": ["exempt", "success", "pending"] }, "cname_target": { "type": "string" },
          "data": { "type": "object", "properties": {
            "records_propagated": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "host": { "type": "string" }, "value": { "type": "string" } } } },
            "records_non_propagated": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "host": { "type": "string" }, "value": { "type": "string" } } } },
            "records_missing": { "$ref": "#/components/schemas/MissingRecords" } } },
          "health": { "enum": ["healthy", "degraded", "broken"], "description": "domain.records_missing and domain.records_restored only" },
          "previous_health": { "enum": ["healthy", "degraded", "broken", null], "description": "domain.records_missing and domain.records_restored only" },
          "reason": { "enum": ["records_missing", "dns_unreachable", "records_restored"], "description": "domain.records_missing and domain.records_restored only" },
          "share_link_id": { "type": "string", "description": "Only on connections started from a shareable link" },
          "application_id": { "type": "string", "description": "webhook.test only" }, "created_at": { "type": "string", "format": "date-time", "description": "webhook.test only" }
        }
      }
    }
  }
}
