{
  "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." },
    {"name":"Agent onboarding","description":"For coding agents, no credentials: a sandbox session at once and a free account for the developer, created only when they open the emailed link. Requests with an Origin header (browsers) are refused with 403."},
    {"name":"OAuth","description":"Authorization server of the MCP server (RFC 8414, 9728, 7591, 7009, 7636, 8707, 9207). Not needed for the REST API, which uses session tokens and HTTP Basic."}
  ],
  "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/agent/sandbox": {"post":{"tags":["Agent onboarding"],"operationId":"startAgentSandbox","summary":"Get a sandbox session (no account)","security":[],"description":"A 30-minute session of a Cnamio test application: every connection goes to the sandbox provider and no real DNS is read or written. Any domain connects; conflict.<domain> and pending.<domain> simulate a record in the way and one that never appears; providerToken \"invalid\" is refused. No body needed (none, or an empty JSON body). Limits: 5 sessions a minute and 20 a day per address; each session may use 20 distinct domains and 30 requests a minute (429 after that: get a new session).","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"client":{"$ref":"#/components/schemas/AgentClient"}}}}}},"responses":{"201":{"description":"Sandbox session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxSession"}}}},"403":{"description":"Sent from a browser (Origin header).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The sandbox is not offered by this server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many sessions from this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},
    "/v1/agent/signup": {"post":{"tags":["Agent onboarding"],"operationId":"startAgentSignup","summary":"Start a free account for the developer","security":[],"description":"Emails the developer the sign-up link (the same as the site's form). Opening it creates the account: a test application (sandbox provider) and a live application on the free plan. Nothing is created before. The answer is the same for a new address and one that already has an account (which receives a sign-in link instead). Ask the developer first: consent true means they agreed to https://cnamio.com/terms and https://cnamio.com/privacy. The email says an agent asked for the account, and the account is created only when the developer accepts the Terms and the Privacy Policy on the screen the link opens. Limits: 3 a minute and 10 a day per address; one email per address per 15 minutes, 4 a day.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","consent"],"properties":{"email":{"type":"string","format":"email"},"consent":{"const":true},"name":{"type":"string","minLength":2,"maxLength":120,"description":"Default: taken from the email."},"company":{"type":"string","minLength":2,"maxLength":120},"locale":{"enum":["en","pt-BR","es"]},"client":{"$ref":"#/components/schemas/AgentClient"}}}}}},"responses":{"202":{"description":"Received","content":{"application/json":{"schema":{"type":"object","required":["received","message","next_steps"],"properties":{"received":{"const":true},"message":{"type":"string"},"next_steps":{"type":"array","items":{"type":"string"}},"sandbox":{"$ref":"#/components/schemas/SandboxSession"}}}}}},"400":{"description":"Invalid email, or consent is not true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sent from a browser (Origin header).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Sign-up is not offered by this server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many sign-ups from this address or for this email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/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. With the application's monitoring switched off nothing is being checked, so this filter matches no connection.", "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" } }
      }
    },
    "/.well-known/oauth-protected-resource/mcp": {
      "get": {
        "tags": [
          "OAuth"
        ],
        "operationId": "getProtectedResourceMetadata",
        "summary": "Protected resource metadata of the MCP server (RFC 9728)",
        "security": [],
        "description": "Also at /.well-known/oauth-protected-resource. /mcp answers 401 with WWW-Authenticate: Bearer resource_metadata=\"…\", scope=\"…\" when a tool that needs credentials is called without any, and 403 error=\"insufficient_scope\" when the token lacks the tool's scope.",
        "responses": {
          "200": {
            "description": "Metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "resource",
                    "authorization_servers"
                  ],
                  "properties": {
                    "resource": {
                      "type": "string",
                      "const": "https://api.cnamio.com/mcp"
                    },
                    "authorization_servers": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "const": "https://api.cnamio.com"
                      }
                    },
                    "scopes_supported": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "domains:read",
                          "domains:write",
                          "share_links:write"
                        ]
                      }
                    },
                    "bearer_methods_supported": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "tags": [
          "OAuth"
        ],
        "operationId": "getAuthorizationServerMetadata",
        "summary": "Authorization server metadata (RFC 8414)",
        "security": [],
        "responses": {
          "200": {
            "description": "Metadata: issuer https://api.cnamio.com, code_challenge_methods_supported [\"S256\"], client_id_metadata_document_supported true, authorization_response_iss_parameter_supported true.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "issuer",
                    "authorization_endpoint",
                    "token_endpoint",
                    "code_challenge_methods_supported"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/oauth/authorize": {
      "get": {
        "tags": [
          "OAuth"
        ],
        "operationId": "authorize",
        "summary": "Start an authorization (opens the consent page)",
        "security": [],
        "description": "Validates the client and the redirect URI (exact match; any port for loopback), then sends the person to the consent page, where they sign in with their account email, pick an application and approve. The answer comes back to redirect_uri with code, state and iss (or error, state and iss). An unknown client or redirect URI gets an error page, never a redirect.",
        "parameters": [
          {
            "name": "response_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "const": "code"
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "description": "A Client ID Metadata Document URL (https) or a client_id from /oauth/register."
            }
          },
          {
            "name": "redirect_uri",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "code_challenge",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 43,
              "maxLength": 128
            }
          },
          {
            "name": "code_challenge_method",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "const": "S256"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 1024
            }
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Space-separated; unknown scopes (offline_access) are ignored; none known: all of them, shown on the consent page."
            }
          },
          {
            "name": "resource",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "const": "https://api.cnamio.com/mcp"
            }
          }
        ],
        "responses": {
          "303": {
            "description": "To the consent page, or back to redirect_uri with an error"
          },
          "400": {
            "description": "Unknown client or redirect URI (HTML page)"
          }
        }
      }
    },
    "/oauth/token": {
      "post": {
        "tags": [
          "OAuth"
        ],
        "operationId": "token",
        "summary": "Exchange a code, or rotate a refresh token",
        "security": [],
        "description": "Public clients send client_id; confidential ones authenticate with client_secret_basic or client_secret_post. A code is single use and lasts two minutes; presenting it twice revokes what it became.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "authorization_code",
                      "refresh_token"
                    ]
                  },
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string"
                  },
                  "code_verifier": {
                    "type": "string"
                  },
                  "redirect_uri": {
                    "type": "string"
                  },
                  "refresh_token": {
                    "type": "string"
                  },
                  "resource": {
                    "type": "string",
                    "const": "https://api.cnamio.com/mcp"
                  },
                  "scope": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tokens",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "access_token",
                    "token_type",
                    "expires_in",
                    "refresh_token",
                    "scope"
                  ],
                  "properties": {
                    "access_token": {
                      "type": "string",
                      "pattern": "^cnm_at_"
                    },
                    "token_type": {
                      "type": "string",
                      "const": "Bearer"
                    },
                    "expires_in": {
                      "type": "integer",
                      "examples": [
                        3600
                      ]
                    },
                    "refresh_token": {
                      "type": "string",
                      "pattern": "^cnm_rt_",
                      "description": "Single use: every refresh returns a new one. Presenting a used one revokes the whole authorization."
                    },
                    "scope": {
                      "type": "string",
                      "examples": [
                        "domains:read domains:write"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "OAuth error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "examples": [
                        "invalid_grant",
                        "invalid_client",
                        "invalid_request",
                        "invalid_target",
                        "invalid_scope",
                        "unsupported_grant_type"
                      ]
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "OAuth error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "examples": [
                        "invalid_grant",
                        "invalid_client",
                        "invalid_request",
                        "invalid_target",
                        "invalid_scope",
                        "unsupported_grant_type"
                      ]
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "OAuth error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "examples": [
                        "invalid_grant",
                        "invalid_client",
                        "invalid_request",
                        "invalid_target",
                        "invalid_scope",
                        "unsupported_grant_type"
                      ]
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/oauth/register": {
      "post": {
        "tags": [
          "OAuth"
        ],
        "operationId": "registerClient",
        "summary": "Dynamic client registration (RFC 7591)",
        "security": [],
        "description": "For clients without a Client ID Metadata Document. redirect_uris: 1 to 10 https URLs, or http on 127.0.0.1, [::1] or localhost. token_endpoint_auth_method none (public) or client_secret_basic (the default) / client_secret_post. Ten registrations per minute per address.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "redirect_uris"
                ],
                "properties": {
                  "redirect_uris": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "client_name": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "token_endpoint_auth_method": {
                    "type": "string",
                    "enum": [
                      "none",
                      "client_secret_basic",
                      "client_secret_post"
                    ]
                  },
                  "grant_types": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "authorization_code",
                        "refresh_token"
                      ]
                    }
                  },
                  "response_types": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "const": "code"
                    }
                  },
                  "client_uri": {
                    "type": "string"
                  },
                  "logo_uri": {
                    "type": "string"
                  },
                  "software_id": {
                    "type": "string"
                  },
                  "software_version": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Registered; client_secret only for confidential clients (shown once)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "client_id"
                  ],
                  "properties": {
                    "client_id": {
                      "type": "string",
                      "pattern": "^ocl_"
                    },
                    "client_secret": {
                      "type": "string"
                    },
                    "client_secret_expires_at": {
                      "type": "integer",
                      "const": 0
                    },
                    "client_id_issued_at": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "OAuth error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "examples": [
                        "invalid_grant",
                        "invalid_client",
                        "invalid_request",
                        "invalid_target",
                        "invalid_scope",
                        "unsupported_grant_type"
                      ]
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "OAuth error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "examples": [
                        "invalid_grant",
                        "invalid_client",
                        "invalid_request",
                        "invalid_target",
                        "invalid_scope",
                        "unsupported_grant_type"
                      ]
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/oauth/revoke": {
      "post": {
        "tags": [
          "OAuth"
        ],
        "operationId": "revokeToken",
        "summary": "Revoke a token (RFC 7009)",
        "security": [],
        "description": "A refresh token ends the whole authorization; an access token ends only itself. Answers 200 whatever the token was.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "token_type_hint": {
                    "type": "string",
                    "enum": [
                      "access_token",
                      "refresh_token"
                    ]
                  },
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done"
          },
          "401": {
            "description": "OAuth error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "examples": [
                        "invalid_grant",
                        "invalid_client",
                        "invalid_request",
                        "invalid_target",
                        "invalid_scope",
                        "unsupported_grant_type"
                      ]
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "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" },
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1 for the MCP server (claude.ai and ChatGPT connectors, MCP clients). Authorization code with PKCE S256 only; access tokens last one hour and are bound to https://api.cnamio.com/mcp and to the one application the person chose. Clients identify with a Client ID Metadata Document (an https URL) or register at /oauth/register.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.cnamio.com/oauth/authorize",
            "tokenUrl": "https://api.cnamio.com/oauth/token",
            "refreshUrl": "https://api.cnamio.com/oauth/token",
            "scopes": {
              "domains:read": "Check domains and follow the application's connections",
              "domains:write": "Start connections (manual or with a provider token)",
              "share_links:write": "Create and revoke connection links"
            }
          }
        }
      }
    },
    "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": {
      "SandboxSession": {"type":"object","required":["application_id","auth_token","expires_at","user_id","mode","sandbox"],"properties":{"application_id":{"type":"string","pattern":"^app_"},"auth_token":{"type":"string","description":"Session token: Authorization: Bearer, with the applicationId header. MCP: the sandboxToken argument."},"expires_at":{"type":"string","format":"date-time","description":"30 minutes after issue."},"user_id":{"type":"string","pattern":"^sbx_","description":"Bound to the session: its connections carry it, and the session sees only them."},"mode":{"const":"test"},"sandbox":{"const":true},"scenarios":{"type":"object","additionalProperties":{"type":"string"}},"how_to_use":{"type":"string"}}},
      "AgentClient": {"type":"object","description":"The agent making the call, for aggregated statistics (only a family label such as claude-code is kept).","properties":{"name":{"type":"string","maxLength":200,"example":"claude-code"},"version":{"type":"string","maxLength":30}}},
      "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. A nameserver answering without authority counts as a zone that could not be read. null: never monitored (a job no longer monitored, see monitored, keeps its last health)." },
      "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" }
        }
      }
    }
  }
}
