Coldrig Byo Domains API

openapi: 3.2.0
info:
  title: Coldrig Dev Byo Domains API
  version: 0.3.0
  contact:
    name: EpiphanyMade
    email: support@coldrig.dev
  license:
    name: MIT
  description: 'Operations tagged byo-domains across 2 of this provider''s published API definitions: coldrig-dev-openapi.yaml, coldrig-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.coldrig.dev
  description: Production API host.
security:
- bearerAuth: []
tags:
- name: byo-domains
paths:
  /byo-domains:
    get:
      operationId: get_byo_domains
      tags:
      - byo-domains
      summary: List every bring-your-own domain for the account
      description: Summary rows only — use GET /byo-domains/{id} for the full intake detail (pre-flight scan, abuse verdict, consent status).
      responses:
        '200':
          description: BYO domain summaries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ByoDomainSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: register_byo_domain
      tags:
      - byo-domains
      summary: Register a bring-your-own domain and run the pre-flight intake scan
      description: Runs the live-infra scan, the abuse gate, and the reputation ladder, returning the starting byoStatus. A live-infra hit hard-refuses NS delegation and falls back to records_to_apply; a primary domain is always records_to_apply, never we_manage_zone. Real DNS delegation activates per-account the same way real sending does — this endpoint is reachable today, but registering a domain does not itself set up anything real until the account is activated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterByoDomainInput'
      responses:
        '201':
          description: Domain registered — intake started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByoDomainRecord'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /byo-domains/{id}:
    get:
      operationId: get_byo_domain
      tags:
      - byo-domains
      summary: One BYO domain's full intake detail
      parameters:
      - $ref: '#/components/parameters/ByoDomainId'
      responses:
        '200':
          description: BYO domain detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByoDomainRecord'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /byo-domains/{id}/poll-dns:
    post:
      operationId: poll_byo_domain_dns
      tags:
      - byo-domains
      summary: Re-check DNS delegation/records for a domain in pending_dns
      description: 'Poll-verify: advances pending_dns → active on success, or → abandoned after a 7-day idle timeout with no verification. A no-op (returns current state) once past pending_dns.'
      parameters:
      - $ref: '#/components/parameters/ByoDomainId'
      responses:
        '200':
          description: Poll result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollDnsResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /byo-domains/{id}/consent:
    post:
      operationId: acknowledge_byo_consent
      tags:
      - byo-domains
      summary: Acknowledge the primary-domain risk disclosure
      description: Required before a primary-domain intake can proceed past pending_consent. acknowledged must be the literal true — there is no default or implied acknowledgment. Idempotent past pending_consent. The acknowledgment documents informed consent; it does not itself remove the business's exposure or substitute for the technical safeguards in §20.1/§20.2.
      parameters:
      - $ref: '#/components/parameters/ByoDomainId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcknowledgeByoConsentInput'
      responses:
        '200':
          description: Consent recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByoDomainRecord'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /byo-domains/{id}/managed-mailboxes:
    post:
      operationId: request_managed_byo_mailboxes
      tags:
      - byo-domains
      summary: Request mailboxes Coldrig sets up on an already-active BYO domain
      description: 'The primary build target: the vendor sets up new mailboxes under the customer''s own domain, reusing the same setup path as the lookalike-domain flow. Requires the domain to already be active (past DNS verification). These are mailboxes Coldrig sets up, so they count toward the standard per-mailbox quantity billing, at your plan''s mailbox price; pass `quoteOnly: true` to preview the new count + projected monthly before setup.'
      parameters:
      - $ref: '#/components/parameters/ByoDomainId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestManagedByoMailboxesInput'
      responses:
        '201':
          description: Mailboxes set up.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedMailboxesResult'
        '202':
          description: 'A large order: it would bring the account more than 20 mailboxes past what its last confirmed payment covered, so nothing was set up or charged. Returns { provisioning: "payment_pending", billing, payment }. Pay at `payment.url`; then repeat this same request.

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - provisioning
                - billing
                - payment
                properties:
                  provisioning:
                    type: string
                    enum:
                    - payment_pending
                  billing:
                    $ref: '#/components/schemas/MailboxBilling'
                  payment:
                    $ref: '#/components/schemas/LargeOrderPayment'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/CapacityPending'
        '502':
          $ref: '#/components/responses/VendorError'
        '503':
          $ref: '#/components/responses/NotActivated'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /byo-domains/{id}/connect-mailbox:
    post:
      operationId: connect_byo_mailbox
      tags:
      - byo-domains
      summary: Declare an existing mailbox connection on a BYO domain
      description: 'Bypasses vendor setup entirely: the caller already holds the OAuth refresh token or SMTP+IMAP app password for a mailbox that already exists. This declares the mailbox the caller is connecting — it is not a claim about this platform''s own outbound send transport. A connected mailbox is billed like any mailbox, at your plan''s mailbox price (the preview shows it), and the billed quantity follows at once; pass `quoteOnly: true` to preview the new count + projected monthly before connecting.'
      parameters:
      - $ref: '#/components/parameters/ByoDomainId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectByoMailboxInput'
      responses:
        '200':
          description: 'Either a quoteOnly preview (nothing was connected; the body is `{ quoteOnly: true, billing }`), or a repeat of an identical connect that already landed (the mailbox is already connected and billed; the body is the existing mailbox, the same as the 201 body, with no `quoteOnly`).

            '
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  required:
                  - quoteOnly
                  - billing
                  properties:
                    quoteOnly:
                      type: boolean
                      enum:
                      - true
                    billing:
                      $ref: '#/components/schemas/MailboxBilling'
                - $ref: '#/components/schemas/ConnectByoMailboxResult'
        '201':
          description: Mailbox connection recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectByoMailboxResult'
        '400':
          description: 'Validation error. Also returned when the address is already connected to this account with different settings, or is a mailbox Coldrig set up; nothing is changed.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
components:
  schemas:
    LargeOrderPayment:
      type: object
      required:
      - url
      - amountCents
      - mailboxes
      - coveredAfter
      - expiresAt
      - text
      description: 'The one hosted card payment page a large order waits on. Its amount is this billing period''s share of the mailboxes past what the last confirmed payment covered, and is taken off the next bill. The cardholder''s bank may ask for a code. Repeating the order returns the same page until it is paid or expires.

        '
      properties:
        url:
          type: string
          description: Open in a browser and pay here.
        amountCents:
          type: integer
        mailboxes:
          type: integer
          description: How many mailboxes past the last confirmed payment this page pays for.
        coveredAfter:
          type: integer
          description: The mailbox count the account's confirmed payments cover once this page is paid.
        expiresAt:
          type: integer
          description: Unix milliseconds.
        text:
          type: string
    RegisterByoDomainInput:
      type: object
      required:
      - domain
      - domainRelationship
      properties:
        domain:
          type: string
          minLength: 3
          maxLength: 253
          description: 'One line of plain text: a line break, tab, control character or invisible text-direction mark is refused (400) naming this field.'
        domainRelationship:
          $ref: '#/components/schemas/DomainRelationshipInput'
    ByoDomainRecord:
      type: object
      required:
      - domainId
      - domain
      - isPrimary
      - dnsMode
      - byoStatus
      - breakerTier
      - reputationBranch
      - scan
      - abuseVerdict
      - consentAcknowledged
      properties:
        domainId:
          type: string
        domain:
          type: string
        isPrimary:
          type: boolean
        dnsMode:
          type: string
          enum:
          - we_manage_zone
          - records_to_apply
        byoStatus:
          type: string
          enum:
          - pending_kyc
          - pending_consent
          - pending_dns
          - active
          - rejected
          - abandoned
        breakerTier:
          type: string
          enum:
          - standard
          - elevated
          - primary
        reputationBranch:
          type:
          - string
          - 'null'
        scan:
          type: object
          additionalProperties: true
          description: Pre-flight live-infra scan result.
        abuseVerdict:
          type: string
          description: Abuse-gate verdict.
        consentAcknowledged:
          type: boolean
    ByoDomainSummary:
      type: object
      required:
      - domainId
      - domain
      - isPrimary
      - dnsMode
      - byoStatus
      - breakerTier
      - reputationBranch
      - mailboxCount
      properties:
        domainId:
          type: string
        domain:
          type: string
        isPrimary:
          type: boolean
        dnsMode:
          type: string
          enum:
          - we_manage_zone
          - records_to_apply
        byoStatus:
          type: string
          enum:
          - pending_kyc
          - pending_consent
          - pending_dns
          - active
          - rejected
          - abandoned
        breakerTier:
          type: string
          enum:
          - standard
          - elevated
          - primary
        reputationBranch:
          type:
          - string
          - 'null'
        mailboxCount:
          type: integer
    DomainRelationshipInput:
      type: string
      enum:
      - fresh_standalone
      - subdomain_of_primary
      - is_primary
      description: 'fresh_standalone = brand-new domain, no history; subdomain_of_primary = a subdomain of the account''s existing primary domain; is_primary = the account''s own flagship business domain.

        '
    ConnectByoMailboxResult:
      type: object
      required:
      - mailboxId
      - email
      - transportKind
      - billing
      properties:
        mailboxId:
          type: string
        email:
          type: string
        transportKind:
          type: string
        billing:
          $ref: '#/components/schemas/MailboxBilling'
    ConnectByoMailboxSmtpInput:
      type: object
      required:
      - kind
      - host
      - port
      - secure
      - user
      - pass
      properties:
        kind:
          type: string
          enum:
          - smtp
        host:
          type: string
        port:
          type: integer
        secure:
          type: boolean
        user:
          type: string
        pass:
          type: string
    ConnectByoMailboxGmailInput:
      type: object
      required:
      - kind
      - clientId
      - clientSecret
      - refreshToken
      properties:
        kind:
          type: string
          enum:
          - gmail_api
        clientId:
          type: string
        clientSecret:
          type: string
        refreshToken:
          type: string
    PollDnsResult:
      type: object
      required:
      - domainId
      - byoStatus
      - verified
      - checksSoFar
      properties:
        domainId:
          type: string
        byoStatus:
          type: string
          enum:
          - pending_kyc
          - pending_consent
          - pending_dns
          - active
          - rejected
          - abandoned
        verified:
          type: boolean
        checksSoFar:
          type: integer
    ConnectByoMailboxInput:
      type: object
      required:
      - email
      - transport
      properties:
        email:
          type: string
          format: email
        quoteOnly:
          type: boolean
          default: false
          description: Quote-before-add — true previews the new count + projected monthly without connecting.
        transport:
          description: 'The mailbox connection the caller already holds — declares an EXISTING credential the caller supplies, not an OAuth flow this API initiates. This describes the mailbox being connected; it is not a claim about this platform''s own outbound send transport.

            '
          oneOf:
          - $ref: '#/components/schemas/ConnectByoMailboxSmtpInput'
          - $ref: '#/components/schemas/ConnectByoMailboxGmailInput'
          - $ref: '#/components/schemas/ConnectByoMailboxGraphInput'
          discriminator:
            propertyName: kind
    RequestManagedByoMailboxesInput:
      type: object
      required:
      - count
      properties:
        count:
          type: integer
          minimum: 1
          maximum: 5
          description: At most 5; on a live account, a domain with no managed mailboxes needs 3-5.
        personaSlug:
          type: string
          minLength: 1
          maxLength: 50
          description: Optional; defaults to a slug of the domain.
        quoteOnly:
          type: boolean
          default: false
          description: Quote-before-add — true previews the new count + projected monthly without setup.
    MailboxBilling:
      type: object
      description: 'Billing projection returned on every mailbox add/remove (no silent capacity addition). `provisionedAfter` is the live mailbox count AFTER the call — reality, not the ask (a capacity-limited partial or a quoteOnly preview both report the true resulting count).

        '
      required:
      - provisionedAfter
      - projectedMonthlyCents
      - formula
      properties:
        provisionedAfter:
          type: integer
          description: Live set-up mailbox count after this operation.
        projectedMonthlyCents:
          type: integer
          description: 'Projected monthly: $49 a month covers the first 3 mailboxes, then $5 a month for each extra mailbox (3-mailbox minimum) — folding any checkout discount.'
        formula:
          type: string
        domainEnding:
          type: object
          description: 'Only on a quoteOnly preview of an order over 10 mailboxes in the account''s first billing month that buys new domains, when the platform''s .co switch is on: they will end in .co unless the real call sends `dotComDomains: true`.

            '
          required:
          - ending
          - newDomains
          - feeCentsEach
          - text
          properties:
            ending:
              type: string
              enum:
              - co
            newDomains:
              type: integer
              description: New domains this order buys.
            feeCentsEach:
              type: integer
              description: The one-time fee per .com domain bought, in cents, added to the next bill.
            text:
              type: string
              description: The same, in one sentence to show the account owner.
        prepay:
          type: object
          description: 'Only on a quoteOnly preview of an order making more than 4 new domains in your first billing month, when the platform''s prepaid-month switch is on: the real call must send `prepaySecondMonth: true` (else 400 `prepay_required`, nothing bought); month 2 is then charged right after the mailboxes are set up, at most `cents`.

            '
          required:
          - months
          - cents
          - text
          properties:
            months:
              type: integer
              enum:
              - 2
              description: The month paid up front is the second one.
            cents:
              type: integer
              description: Month 2 at this order's mailbox count.
            text:
              type: string
              description: The same, in one sentence to show the account owner.
    ConnectByoMailboxGraphInput:
      type: object
      required:
      - kind
      - mode
      - tenantId
      - clientId
      - clientSecret
      properties:
        kind:
          type: string
          enum:
          - ms_graph
        mode:
          type: string
          enum:
          - delegated
          - app_only
        tenantId:
          type: string
        clientId:
          type: string
        clientSecret:
          type: string
        refreshToken:
          type: string
          description: Optional for app_only mode.
    ManagedMailboxesResult:
      type: object
      required:
      - mailboxEmails
      - billing
      properties:
        mailboxEmails:
          type: array
          items:
            type: string
        billing:
          $ref: '#/components/schemas/MailboxBilling'
    AcknowledgeByoConsentInput:
      type: object
      required:
      - acknowledged
      properties:
        acknowledged:
          type: boolean
          enum:
          - true
          description: 'Must be the literal true — a separate, unbundled risk acknowledgment.

            '
  responses:
    CapacityPending:
      description: 'Setup is paused while Coldrig support checks recent purchases on this account. Not a failure, and nothing was charged for this step; sending, existing mailboxes and the plan are not affected. `reason` names why. Once support finishes, repeating the same request (same idempotency key) completes it.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
                enum:
                - capacity_pending
              reason:
                type: string
                enum:
                - purchase_hold
            required:
            - error
            - code
            - reason
    NotFound:
      description: Resource not found, or not owned by the authenticated account.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    VendorError:
      description: 'A real vendor call failed (domain registrar or mailbox provider) — materially different from a bug in this service. `step` names the vendor operation that failed when derivable; `retryable` is the adapter''s own grade, so a caller can back off instead of guessing.


        THE GRADE IS TWO INDEPENDENT QUESTIONS. `retryable` says whether an immediate re-attempt can succeed on its own. `operatorActionable` says whether Coldrig''s team can clear the refusal — funding a provider account, rotating a credential, un-suspending a workspace — after which your SAME request, with the same idempotency key, completes. When it is true the `code` is `vendor_operator_blocked`: do not change your inputs and do not give up, because nothing about the request is wrong. When both are false the refusal is yours to fix or to escalate.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
                enum:
                - vendor_error
                - vendor_operator_blocked
              step:
                type:
                - string
                - 'null'
                description: The vendor operation that failed, when derivable from the underlying error message.
              retryable:
                type: boolean
              operatorActionable:
                type: boolean
                description: 'Present and true only on `vendor_operator_blocked`: someone at Coldrig can clear this, and the identical retry then completes. Absent means false.

                  '
            required:
            - error
            - code
            - retryable
    Unauthorized:
      description: Missing, invalid, or inactive bearer token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    NotActivated:
      description: 'A required vendor integration is not yet enabled for this account. Nothing was charged. This condition has no automatic notification to Coldrig''s team behind it, so the response says so and points at contact_operator rather than implying a human is already on it.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
                enum:
                - not_activated
              step:
                type:
                - string
                - 'null'
            required:
            - error
            - code
    ValidationError:
      description: Request body failed schema validation.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  parameters:
    ByoDomainId:
      name: id
      in: path
      required: true
      description: 'The MCP tools `get_byo_domains` and `configure_byo_domain` take this same identifier as an `id` argument (there is no URL path in MCP tool calls).

        '
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Token returned by POST /signup. One token = one separate account. An app connected with "Sign in with Coldrig" (OAuth) holds its own short-lived token for the same account: it is accepted on the hosted MCP endpoint (/mcp) only, and on no REST route.

        '
    dashboardSessionCookie:
      type: apiKey
      in: cookie
      name: cs_dashboard_session
      description: 'httpOnly session cookie minted by POST /dashboard/session (30-day TTL). Alternative to bearerAuth for /dashboard/* routes only, used by the optional human dashboard SPA. A cookie-authed mutating request (any method other than GET/HEAD) must also send the `X-Coldstart-Client: dashboard` header (global CSRF guard) — bearer-authed requests are exempt.

        '
x-refined-from:
- coldrig-dev-openapi.yaml
- coldrig-dev-openapi.yml