Coldrig Leads API

openapi: 3.2.0
info:
  title: Coldrig Dev Leads API
  version: 0.3.0
  contact:
    name: EpiphanyMade
    email: support@coldrig.dev
  license:
    name: MIT
  description: 'Operations tagged leads 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: Leads
paths:
  /leads:
    get:
      operationId: list_leads
      tags:
      - Leads
      summary: List/export leads with their contact-level disposition, cursor-paginated
      description: Also the export surface — paginate to dump the full book of business as JSON; there is no separate CSV endpoint.
      parameters:
      - name: campaign
        in: query
        schema:
          type: string
          minLength: 1
          maxLength: 200
      - name: interestStatus
        in: query
        schema:
          $ref: '#/components/schemas/LeadInterestStatus'
      - name: suppressed
        in: query
        schema:
          type: boolean
      - name: replied
        in: query
        schema:
          type: boolean
      - name: cursor
        in: query
        schema:
          type: string
          minLength: 1
          maxLength: 500
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: Lead list page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadListPage'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /leads/suppress:
    post:
      operationId: suppress_lead
      tags:
      - Leads
      summary: Permanently suppress an email address account-wide
      description: The manual/free-text "stop emailing me" path for opt-outs the strict typed-unsubscribe matcher misses. Cancels every pending send and marks every campaign-lead row for this email suppressed. There is no un-suppress endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuppressLeadInput'
      responses:
        '200':
          description: Suppressed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuppressLeadResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /leads/disposition:
    post:
      operationId: update_lead
      tags:
      - Leads
      summary: Record a contact-level lead disposition (interest status, notes, tags)
      description: 'Upserts the durable, contact-level lead_dispositions row keyed by email — visible across every campaign that lists the contact. A partial patch: only the fields you pass are changed; at least one of interestStatus, notes, or tags is required.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLeadInput'
      responses:
        '200':
          description: Disposition upserted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadDispositionView'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
components:
  schemas:
    UpdateLeadInput:
      type: object
      required:
      - email
      description: At least one of interestStatus, notes, or tags must be present — a call with none has nothing to persist.
      properties:
        email:
          type: string
          format: email
        interestStatus:
          $ref: '#/components/schemas/LeadInterestStatus'
        notes:
          type: string
          maxLength: 5000
        tags:
          type: array
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 100
        objection:
          type: string
          enum:
          - has_solution
          - no_budget
          - no_need
          - timing
          - trust
          description: Only with interestStatus objection.
        until:
          type: string
          format: date
          description: Only with interestStatus not_now or out_of_office — the date to follow up or that they return.
    LeadListPage:
      type: object
      required:
      - leads
      - nextCursor
      properties:
        leads:
          type: array
          items:
            type: object
            required:
            - leadId
            - email
            - firstName
            - company
            - campaignId
            - campaignName
            - globalStatus
            - interestStatus
            - notes
            - tags
            - suppressed
            - lastEventType
            - lastEventTs
            - createdAt
            properties:
              leadId:
                type: string
              email:
                type: string
              firstName:
                type: string
              company:
                type: string
              campaignId:
                type: string
              campaignName:
                type: string
              globalStatus:
                type: string
              interestStatus:
                $ref: '#/components/schemas/LeadInterestStatus'
              notes:
                type: string
              tags:
                type: array
                items:
                  type: string
              suppressed:
                type: boolean
              lastEventType:
                type:
                - string
                - 'null'
              lastEventTs:
                type:
                - integer
                - 'null'
              createdAt:
                type: integer
        nextCursor:
          type:
          - string
          - 'null'
    LeadDispositionView:
      type: object
      required:
      - email
      - interestStatus
      - notes
      - tags
      - source
      - updatedAt
      properties:
        email:
          type: string
        interestStatus:
          $ref: '#/components/schemas/LeadInterestStatus'
        notes:
          type: string
        tags:
          type: array
          items:
            type: string
        source:
          type: string
          enum:
          - dashboard
          - mcp
          - api
          - system
        updatedAt:
          type: integer
    LeadInterestStatus:
      type: string
      enum:
      - none
      - interested
      - meeting_booked
      - not_now
      - not_interested
      - bad_fit
      - out_of_office
      - wrong_person
      - referral
      - question
      - objection
      - hostile
      description: 'Also labels the contact''s latest reply for experiments (reply taxonomy v1): interested, meeting_booked and referral are positive; not_now, question and wrong_person neutral; not_interested, objection, bad_fit and hostile negative; none clears the label. out_of_office reschedules the follow-up past the return date instead of treating silence as disinterest; wrong_person drives a referral ask. do_not_contact is deliberately not a member — that intent routes to POST /leads/suppress instead.

        '
    SuppressLeadResult:
      type: object
      required:
      - suppressed
      - alreadySuppressed
      properties:
        suppressed:
          type: boolean
          enum:
          - true
        alreadySuppressed:
          type: boolean
    SuppressLeadInput:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
        reason:
          type: string
          enum:
          - manual
          default: manual
          description: 'Pinned to "manual" — the only value an external caller can claim. bounce/soft_bounce/complaint/unsubscribe are exclusively system-derived elsewhere.

            '
        note:
          type: string
          maxLength: 2000
          description: Accepted for schema symmetry; not persisted (suppressions carries no note column).
  responses:
    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