Coldrig Sandbox API

openapi: 3.2.0
info:
  title: Coldrig Dev Sandbox API
  version: 0.3.0
  contact:
    name: EpiphanyMade
    email: support@coldrig.dev
  license:
    name: MIT
  description: 'Operations tagged sandbox 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: Sandbox
paths:
  /demo/run:
    post:
      operationId: demo_run
      tags:
      - Sandbox
      summary: Run the free test-mode demo (test-mode accounts only)
      description: 'On a trial account, a campaign you launch plays out by itself as a simulation, with no demo step and whatever its sending hours, and no email reaches a real inbox. Its sends, replies, bounces and follow-ups show in `campaign_results`, `metrics` and `inbox`. A short list is fully played out when the launch answers; a longer list answers with part of it played and finishes by itself, with no further call, and reading the results again shows the counts grow. Contacts you add and a campaign you resume play out the same way. A campaign launched before `setup_infrastructure` waits and starts by itself once setup has made the mailboxes. The launch, add-contacts and resume answers of a trial account carry `simulation` (`sent`, `replies`, `bounces`, `complaints`, `waiting` and, when `waiting` is above zero, `reason`), counting what that call played; a paid account''s answers have no `simulation`. Among the contacts whose address has no marker word, the 2nd replies and, from three contacts up, the last one bounces; an address whose part before the `@` contains `complaint` (a complaint), `softbounce` (a soft bounce), `bounce` (a hard bounce) or `reply` (a reply) gets that outcome instead. Nothing simulated pauses, throttles or replaces anything, on the trial or after you pay, and going live removes every bounce and complaint the simulation put on your suppression list, so those contacts can be mailed; an unsubscribe and an entry you added by hand stay. A trial account can launch up to 5 test campaigns in any 24 hours, each holding up to 100 contacts, which is enough for a small test. Both are limits of the trial, not of Coldrig: going live removes them. Nothing in a campaign launched on the trial is ever really sent: when the account goes live, the emails it still has waiting are canceled and it cannot be resumed or added to, so launch a new campaign to send real email. To see the built-in sample campaign instead, call this endpoint (HTTP only, not an MCP tool; send no body). It moves the account''s clock forward 32 days, launches its own built-in sample campaign to contacts at `demo-leads.coldrig.dev`, sends step 1, reads the test-mode inbox, sends step 2 to the contacts that did not reply or bounce, and reads it again. Run it after `setup_infrastructure`: with no mailboxes it sends nothing. The built-in campaign stays listed as active, is replaced by the next run, and cannot be resumed or added to. Any other plan gets 403; at most one run per minute and 20 per account in total (429 beyond either).'
      responses:
        '200':
          description: The run's totals.
          content:
            application/json:
              schema:
                type: object
                required:
                - sent
                - replies
                - bounces
                - complaints
                - stopOnReplyProof
                - sampleThread
                properties:
                  sent:
                    type: integer
                  replies:
                    type: integer
                  bounces:
                    type: integer
                  complaints:
                    type: integer
                  stopOnReplyProof:
                    type:
                    - object
                    - 'null'
                    description: A replied contact and whether its remaining steps were cancelled; null when nobody replied.
                    required:
                    - leadEmail
                    - remainingStepsCancelled
                    properties:
                      leadEmail:
                        type: string
                      remainingStepsCancelled:
                        type: boolean
                  sampleThread:
                    type:
                    - object
                    - 'null'
                    additionalProperties: true
                    description: The replied contact's thread (same shape as GET /threads/{id}); null when nobody replied.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The account is not a test-mode account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '429':
          description: A run in the last minute, or the account's 20 runs used.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
components:
  responses:
    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