CustomDomain Monitor API

openapi: 3.2.0
info:
  title: Customdomain Ai Monitor API
  version: '1.0'
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  description: 'Operations tagged Monitor across 2 of this provider''s published API definitions: customdomain-ai-openapi-original.json, customdomain-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.customdomain.ai/v1
  description: Hosted control-plane
- url: http://localhost:8080/v1
  description: Local control-plane
security:
- apiKey: []
tags:
- name: Monitor
  description: Checking declared records against live public DNS (drift).
paths:
  /connections/{id}/monitor:
    get:
      operationId: getConnectionMonitor
      summary: What the drift monitor last found for the domain, and what was done
      tags:
      - Monitor
      description: 'Every live domain is checked against its records once an hour. This returns the last check (when, the result, the drifted records with expected and observed values), what was done about drift (put back automatically with the continuous access CustomDomain™ holds, or left for the tenant because the record was changed rather than removed, because there is no continuous access, or because automatic repair is not switched on), whether repairs are automatic for this domain and why, the records it is held to, and the drift history. An end user''s widget token (scope `connect`) reads this only when it is bound to the domain and minted with the connection''s own `end_user_ref`; use an API key otherwise.


        Automatic repair runs only where the deployment switched it on (`MONITOR_AUTO_REPAIR`; `repair.paused` is true otherwise). It puts back only the record sets that disappeared, from the records CustomDomain™ wrote (a kept Domain Connect authorization re-applies its template, the only write it allows), and only for drift that began after a clean check. A record missing since monitoring started is left for the tenant. Repairs are paced and capped per hourly pass and per provider account, and after 3 repairs of a domain within 24 hours the monitor stops and reports `fix_failed`.'
      security:
      - widgetJWT: []
      - apiKey: []
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The monitoring state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorView'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.customdomain.ai/v1
      description: Hosted control-plane
    - url: http://localhost:8080/v1
      description: Local control-plane
  /monitor:check:
    post:
      operationId: checkRecords
      summary: Check declared baseline records against live public DNS
      tags:
      - Monitor
      description: Resolves each baseline record and reports whether it is still present. This is what the SDK's `checkRecords` rides on. Read-only; performs no writes.
      security:
      - widgetJWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domain
              - baseline
              properties:
                domain:
                  type: string
                baseline:
                  type: array
                  items:
                    type: object
                    properties:
                      subdomain:
                        type: string
                      type:
                        type: string
                      values:
                        type: array
                        items:
                          type: string
      responses:
        '200':
          description: Drift report
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.customdomain.ai/v1
      description: Hosted control-plane
    - url: http://localhost:8080/v1
      description: Local control-plane
  /monitor/domains:
    get:
      operationId: listMonitoredDomains
      summary: Every domain of the workspace with its last drift check
      tags:
      - Monitor
      description: The monitoring state of the domains in the API key's workspace (or one application with `app_id`), the ones needing attention first, a page at a time, with counts over every domain. Pass the previous page's `next_cursor` as `cursor` for the next page; there is no `next_cursor` on the last one. The per domain detail (watched records, repair route, history) is on `GET /connections/{id}/monitor`.
      security:
      - apiKey: []
      parameters:
      - name: app_id
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 200
        description: Domains per page; a larger value is read as 1000.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: The previous page's `next_cursor`.
      responses:
        '200':
          description: One page of domains, and a summary of all of them
          content:
            application/json:
              schema:
                type: object
                required:
                - domains
                - summary
                - every
                - auto_repair
                properties:
                  every:
                    type: string
                  auto_repair:
                    type: boolean
                    description: Whether this deployment puts missing records back automatically (`MONITOR_AUTO_REPAIR`).
                  next_cursor:
                    type: string
                    description: Present when more domains follow; pass it as `cursor`.
                  summary:
                    type: object
                    properties:
                      domains:
                        type: integer
                      watched:
                        type: integer
                      ok:
                        type: integer
                      drift:
                        type: integer
                      needs_action:
                        type: integer
                      inconclusive:
                        type: integer
                      unconfirmed:
                        type: integer
                      not_checked:
                        type: integer
                  domains:
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/MonitorView'
                      - type: object
                        properties:
                          application_id:
                            type: string
                          status:
                            type: string
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.customdomain.ai/v1
      description: Hosted control-plane
    - url: http://localhost:8080/v1
      description: Local control-plane
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string
  responses:
    Error:
      description: 'Error envelope: {code, title, details}.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    DriftRecord:
      type: object
      required:
      - subdomain
      - type
      - verdict
      - expected
      properties:
        subdomain:
          type: string
          description: The record's name relative to the domain ("@" for the domain itself).
        type:
          type: string
        verdict:
          type: string
          enum:
          - record_missing
          - record_changed
        expected:
          type: array
          items:
            type: string
        observed:
          type: array
          items:
            type: string
    MonitorView:
      type: object
      required:
      - connection_id
      - domain
      - watched
      - active
      - every
      - last_checked_at
      - result
      - drift
      - checked
      - repair
      - alerts
      properties:
        connection_id:
          type: string
        domain:
          type: string
        watched:
          type: boolean
        active:
          type: boolean
        every:
          type: string
          description: How often the domain is checked (hour).
        last_checked_at:
          type:
          - string
          - 'null'
          format: date-time
        next_check_at:
          type: string
          format: date-time
        result:
          type: string
          enum:
          - ok
          - drift
          - inconclusive
          - unconfirmed
          - not_checked
          - not_watched
          description: 'The last check. `drift` is only reported after a second, independent look at the zone''s own nameservers confirmed it; `inconclusive` means the lookup did not answer and the previous finding stands; `unconfirmed` means the first lookup saw a change the zone''s own nameservers could not be asked to confirm (see `reason`): earlier drift stands and nothing is restored.'
        reason:
          type: string
          enum:
          - ns_lookup_failed
          - timeout
          - all_servers_refused
          - no_server_answered
          - delegated
          - unsupported_type
          description: Set when `result` is `unconfirmed`, why the nameservers could not confirm.
        unconfirmed_checks:
          type: integer
          description: Set when `result` is `unconfirmed`, how many checks in a row. At 3 the workspace gets one inbox entry.
        drift_since:
          type: string
          format: date-time
        drift:
          type: array
          items:
            $ref: '#/components/schemas/DriftRecord'
        checked:
          type: integer
          description: Records compared in the last check.
        error:
          type: string
        action:
          type: object
          description: 'What was done about the drift: `auto_fixed` (put back), `fix_failed` (the repair failed, did not hold, or the records were put back 3 times in 24 hours and disappeared again) or `action_required` (left for the tenant).'
          properties:
            kind:
              type: string
              enum:
              - auto_fixed
              - fix_failed
              - action_required
            at:
              type: string
              format: date-time
            description:
              type: string
        attention:
          type: string
          enum:
          - action_required
          - fix_failed
          - drift
          description: Set while drift needs the tenant (action_required, fix_failed) or is being repaired (drift).
        repair:
          type: object
          required:
          - automatic
          - detail
          properties:
            automatic:
              type: boolean
              description: True when CustomDomain™ holds continuous access and puts disappeared records back itself.
            paused:
              type: boolean
              description: 'True when CustomDomain™ holds the access (`via`) but this deployment has automatic repair switched off (`MONITOR_AUTO_REPAIR`): missing records are reported, not put back. Omitted otherwise.'
            via:
              type: string
              enum:
              - managed_dns
              - sign_in
              - domain_connect
              - provider_account
            detail:
              type: string
        alerts:
          type: object
          properties:
            webhooks:
              type: boolean
            email:
              type: boolean
        watching:
          type: array
          description: The records the domain is held to.
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
              value:
                type: string
        history:
          type: array
          items:
            $ref: '#/components/schemas/DomainEvent'
    DomainEvent:
      type: object
      required:
      - id
      - domain
      - kind
      - created_at
      properties:
        id:
          type: string
        application_id:
          type: string
        connection_id:
          type: string
        domain:
          type: string
        kind:
          type: string
          description: One of connection.created, connection.applied, connection.live, connection.failed, connection.records.updated, connection.reapply.failed, connection.records_outdated, connection.disconnected, records.removed, records.rewritten, certificate.issued, certificate.renewed, certificate.failed, certificate.expiring, certificate.removed, drift.found, drift.fixed, drift.fix_failed, drift.action_required, drift.restored, access.granted, access.revoked, access.needs_reconnect, nameservers.started, nameservers.dnssec_cleared, nameservers.changed, nameservers.active, nameservers.failed, nameservers.rolled_back, nameservers.drifted. A connection or certificate kind that is also a webhook event type is written with the webhook, so the timeline and an integrator see the same history.
        detail:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
      - code
      - title
      properties:
        code:
          type: string
          description: stable machine code, e.g. invalid_request, unauthorized, not_found, service_unavailable, internal_error
        title:
          type: string
          description: human-readable summary
        details:
          type: string
          description: optional extra context
  securitySchemes:
    managementKey:
      type: http
      scheme: bearer
      description: Operator management key. Gates provisioning + reads across tenants.
    provisionSecret:
      type: apiKey
      in: header
      name: X-Provision-Secret
      description: Narrow secret held by the customer console's server, for signup provisioning and its other server to server calls (also accepted as a Bearer token, except on POST /audit, where a Bearer is always a tenant credential).
    apiKey:
      type: http
      scheme: bearer
      description: Long-lived tenant API key, cd_live_… (production) or cd_test_… (staging, development), stored hashed. Keys created before the switch to cd_ start with sk_live_… / sk_test_… and are still accepted. Scoped to the owning application's tenant.
    widgetJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived widget JWT minted server-side via POST /v1/tokens. Scoped to one application (and optionally one domain).
    browserSession:
      type: http
      scheme: bearer
      description: The session token of one cloud browser sign in, returned by `POST /browser-sessions:redeem`. It binds one session, one connection and one workspace, lives at most as long as the session, and stops working the moment the session ends. It lives in the popup's memory only.
    agentToken:
      type: oauth2
      description: 'A delegated agent access token: an ES256 JWT that lives 15 minutes, sent as a bearer token. A person approves an agent in the console and the agent exchanges its authorization code (with PKCE) at the token endpoint. The token carries the workspace, the one application the grant is bound to, the grant, the approved scopes and its audience, and is verified against `/.well-known/jwks.json`. A route that accepts it lists the scope it needs; a token without the scope is refused with `403`, and a connection or order of another application answers `404`.'
      flows:
        authorizationCode:
          authorizationUrl: https://api.customdomain.ai/oauth/agent/authorize
          tokenUrl: https://api.customdomain.ai/oauth/agent/token
          refreshUrl: https://api.customdomain.ai/oauth/agent/token
          scopes:
            domains:read: Look at availability, connections, records, certificates, diagnoses, orders and the billing standing.
            domains:connect: Connect a domain, recheck it, reapply its records and start a one click setup.
            domains:disconnect: Remove a connected domain. The call must name the domain.
            domains:purchase: Buy a domain, up to the grant's monthly spend cap.
x-refined-from:
- customdomain-ai-openapi-original.json
- customdomain-ai-openapi.yml