Coldrig Account API

openapi: 3.2.0
info:
  title: Coldrig Dev Account API
  version: 0.3.0
  contact:
    name: EpiphanyMade
    email: support@coldrig.dev
  license:
    name: MIT
  description: 'Operations tagged account 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: Account
paths:
  /checkout:
    post:
      operationId: create_checkout_link
      tags:
      - Account
      summary: Start (or upgrade to) the paid managed plan — returns a hosted Stripe Checkout…
      description: 'Subscribes the account to the single `managed` plan: $49 a month covers the first 3 mailboxes and each extra mailbox is $5 a month (3-mailbox / $49 minimum; no setup fee, no domain fee; an account already paying keeps its own minimum and price). `mailboxes` (3 or more) seeds the initial quote only — the billed quantity then TRACKS the account''s live set-up mailbox count, never a commitment for mailboxes not yet set up. Returns a hosted Stripe Checkout URL to open and pay. `mode` is `"simulated"` only in a fully-unarmed test environment where no real purchase is possible; `"stripe"` once real billing is armed. The link opens Stripe''s checkout page; your agent can pay it itself (with a browser tool and a Link agent wallet or a card) or pass it to whoever pays. The MCP tool `create_checkout_link` is this same operation over MCP; it is how an app connected with "Sign in with Coldrig" creates the link (the tool itself only creates it).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mailboxes
              properties:
                mailboxes:
                  type: integer
                  minimum: 3
                  description: Initial committed mailbox count (3 or more).
                interval:
                  type: string
                  enum:
                  - month
                  default: month
                  description: Monthly billing only. Yearly billing is closed.
      responses:
        '201':
          description: Hosted checkout session created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /cancel:
    post:
      operationId: cancel_subscription
      tags:
      - Account
      summary: Cancel the subscription, at the end of the billing period (default) or…
      description: 'The MCP tool `cancel_subscription` is this same operation over MCP; it changes nothing until it is called with `confirm: true`. The body is optional; an empty body means `{ "immediate": false }`. Default (`immediate: false`): the account is marked `canceling` as soon as this call lands, campaigns already running keep sending until the paid period ends (see `sendingStopsAt` on GET /account), then all sending stops (an account that is not paid up stops sending at once), and mailboxes and domains are NOT released by this call (`teardown` is `null`). `immediate: true`: the account is marked `canceled`, campaigns are stopped, every mailbox is released right away and cannot be brought back, and domains we bought for you are released too (a connected domain is not touched); `teardown` counts what was released. Calling it again after an immediate cancel returns the recorded teardown with `alreadyCanceled: true` and releases nothing more. The dashboard Billing page calls this same route. A cancel is refused while a setup is running (retry when it finishes). Mailboxes added since the last invoice are billed on the final invoice of an immediate cancel. The call tells Stripe before it changes the account: the default stops the subscription from renewing (`periodEndsAt` is the end of the paid period, from Stripe, when sending continues until then), and `immediate: true` ends the subscription at Stripe now: no credit or refund for the unused period, and what was added since the last invoice is billed on the final invoice. If Stripe refuses or gives no clear answer, nothing changes on the account and the call answers 502.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                immediate:
                  type: boolean
                  default: false
                  description: false = end of the billing period (default); true = now.
      responses:
        '200':
          description: Cancellation recorded (or the earlier immediate cancel replayed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          description: Request body too large.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '502':
          description: 'Stripe refused the cancellation (`stripe_refused`) or gave no clear answer (`stripe_unknown`). The cancellation could not be confirmed with the billing provider. Repeat the call; repeating is safe.

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
                    enum:
                    - stripe_refused
                    - stripe_unknown
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /billing/portal:
    post:
      operationId: billing_portal
      tags:
      - Account
      summary: Get a Stripe-hosted billing page where the card on file is updated
      description: 'HTTP-only (not an MCP tool). Send an empty body: it is never read, and the Stripe customer is always the caller''s own, so no body field can name another account. Returns the URL of a one-time Stripe-hosted page; the page''s return address is the dashboard Billing page. `409 no_stripe_customer` means the account has no Stripe billing record yet (go live first). `502 billing_portal_unavailable` means Stripe could not open the page right now; the Stripe text is not passed through.'
      responses:
        '200':
          description: Billing page URL.
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                properties:
                  url:
                    type: string
                    format: uri
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: This account has no Stripe billing record yet.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - code
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                    - no_stripe_customer
        '502':
          description: Stripe could not open the billing page right now.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - code
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                    - billing_portal_unavailable
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /billing/invoices:
    get:
      operationId: billing_invoices
      tags:
      - Account
      summary: The account's past invoices (the list the dashboard Billing page shows)
      description: 'HTTP-only (not an MCP tool). Read-only. Returns the first page of the caller''s own Stripe invoices (never another account''s), as Stripe returns them; `hasMore` is true when the billing portal (POST /billing/portal) holds more. An account that has not gone live has no invoices: an empty list, not an error. `502 invoices_unavailable` means Stripe could not be read right now; the Stripe text is not passed through.'
      responses:
        '200':
          description: One page of invoices.
          content:
            application/json:
              schema:
                type: object
                required:
                - invoices
                - hasMore
                properties:
                  hasMore:
                    type: boolean
                  invoices:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - number
                      - date
                      - amountCents
                      - currency
                      - status
                      - hostedInvoiceUrl
                      - pdfUrl
                      properties:
                        id:
                          type: string
                        number:
                          type:
                          - string
                          - 'null'
                          description: The number printed on the invoice; null until Stripe numbers it.
                        date:
                          type: string
                          format: date-time
                          description: When Stripe created the invoice (ISO 8601 UTC).
                        amountCents:
                          type: integer
                          description: The invoice total in the currency's smallest unit.
                        currency:
                          type: string
                        status:
                          type: string
                          description: 'Stripe''s invoice status: open, paid, uncollectible or void (drafts are not listed).'
                        hostedInvoiceUrl:
                          type:
                          - string
                          - 'null'
                          format: uri
                        pdfUrl:
                          type:
                          - string
                          - 'null'
                          format: uri
        '401':
          $ref: '#/components/responses/Unauthorized'
        '502':
          description: Stripe could not be read right now.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - code
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                    - invoices_unavailable
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /metrics:
    get:
      operationId: metrics
      tags:
      - Account
      summary: Account-wide outcome totals across all campaigns (sent, reply, bounce…
      responses:
        '200':
          description: Metrics snapshot.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /account:
    get:
      operationId: account
      tags:
      - Account
      summary: Usage, billing state, and quota for the account
      responses:
        '200':
          description: Account snapshot.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  sendingStopsAt:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    description: 'While a cancellation at the end of the paid period is scheduled: the ISO 8601 UTC time campaigns already running stop sending (the end of the period paid for). `null` otherwise, including an account that stopped sending at once.

                      '
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /connected-apps:
    get:
      operationId: get_connected_apps
      tags:
      - Account
      summary: List the apps connected to this account with "Sign in with Coldrig"
      description: Apps such as ChatGPT or Claude that were connected through "Sign in with Coldrig". `name` is what the app called itself and is not verified; `redirectHost` is where its sign-in returned; `connectedAt` is when it connected (epoch milliseconds). API keys are not listed. Read-only.
      responses:
        '200':
          description: The connected apps, oldest first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  apps:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        redirectHost:
                          type: string
                        connectedAt:
                          type: integer
                          description: Epoch milliseconds.
                      required:
                      - id
                      - name
                      - redirectHost
                      - connectedAt
                required:
                - apps
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /connected-apps/{id}:
    delete:
      operationId: disconnect_app
      tags:
      - Account
      summary: Disconnect one app connected with "Sign in with Coldrig"
      description: 'The app is signed out on its next call and cannot refresh its access; webhooks it created keep running until you delete them (DELETE /webhook-subscriptions/{id}). Disconnecting the app that is making this call is allowed: this call still answers, then that app is signed out. An unknown id, or another account''s id, is a 404. The MCP tool `disconnect_app` takes the same identifier as an `id` argument (there is no URL path in MCP tool calls).'
      parameters:
      - name: id
        in: path
        required: true
        description: The connected app's id, from GET /connected-apps.
        schema:
          type: string
          minLength: 1
          maxLength: 64
      responses:
        '200':
          description: Disconnected.
          content:
            application/json:
              schema:
                type: object
                properties:
                  disconnected:
                    type: boolean
                required:
                - disconnected
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
components:
  schemas:
    CancelTeardown:
      type: object
      description: 'What an immediate cancel released. `mailboxReleaseFailures` counts mailboxes the provider refused to release; they are still live.

        '
      required:
      - reason
      - effective
      - domainsReleased
      - mailboxesReleased
      - mailboxReleaseFailures
      - campaignsStopped
      - annualDomainLiabilityCents
      - ts
      properties:
        reason:
          type: string
          enum:
          - voluntary_cancel
          - abuse_terminate
        effective:
          type: string
        domainsReleased:
          type: integer
        mailboxesReleased:
          type: integer
        mailboxReleaseFailures:
          type: integer
        campaignsStopped:
          type: integer
        annualDomainLiabilityCents:
          type: integer
        ts:
          type: integer
          description: Epoch milliseconds.
    CancelResult:
      type: object
      description: '`effective` is `end_of_period` or `immediate`. `teardown` is `null` for an end-of-period cancel (nothing is released by that call) and the release summary for an immediate one. `periodEndsAt` is the end of the paid period as Stripe gave it when this call scheduled an end-of-period cancel that keeps running campaigns sending until then, and `null` otherwise (an immediate cancel, a repeated call, an account with no Stripe subscription, or one that was not paid up, which stops sending at once).

        '
      required:
      - alreadyCanceled
      - billingState
      - effective
      - teardown
      - periodEndsAt
      properties:
        alreadyCanceled:
          type: boolean
        billingState:
          type: string
          description: '`canceling` or `canceled` right after the call.'
        effective:
          type: string
          enum:
          - end_of_period
          - immediate
        periodEndsAt:
          type:
          - integer
          - 'null'
          description: 'Epoch milliseconds, from Stripe: when sending stops; `null` when this call stored no date.'
        teardown:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/CancelTeardown'
    CheckoutResult:
      type: object
      description: '`mode` is `"simulated"` only when this environment cannot reach real vendor billing at all (no Stripe key wired, no engine armed) — a fully-unarmed test environment; otherwise `"stripe"`. `url` is the hosted Checkout link to open and pay. `sessionId` identifies the checkout session; it is re-validated account-scoped server-side on the return leg, never trusted as a bare credential. `forAgents` is plain-language guidance for the calling agent on how to complete this checkout (pay the hosted page itself with a browser tool, or pass the URL to whoever pays); its wording varies by `mode`.

        '
      required:
      - mode
      - url
      - sessionId
      - forAgents
      properties:
        mode:
          type: string
          enum:
          - stripe
          - simulated
        url:
          type: string
          format: uri
        sessionId:
          type: string
        forAgents:
          type: string
  responses:
    NotFound:
      description: Resource not found, or not owned by the authenticated account.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    ValidationError:
      description: Request body failed schema validation.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    Unauthorized:
      description: Missing, invalid, or inactive bearer token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                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