Coldrig Messages API

openapi: 3.2.0
info:
  title: Coldrig Dev Messages API
  version: 0.3.0
  contact:
    name: EpiphanyMade
    email: support@coldrig.dev
  license:
    name: MIT
  description: 'Operations tagged messages 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: Messages
paths:
  /messages:
    get:
      operationId: list_messages
      tags:
      - Messages
      summary: List this account's system and Coldrig-team messages, cursor-paginated
      description: msgchannel increment 3. Unacked messages sort first (newest first within that group), then acked ones (also newest first). Use POST /messages/{id}/ack to acknowledge one by id so it stops resurfacing. GET /infrastructure-status also inlines the newest 5 unacked messages for a quick glance — this is the full paginated surface.
      parameters:
      - 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: Message list page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageListPage'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /messages/{id}/ack:
    post:
      operationId: ack_message
      tags:
      - Messages
      summary: Acknowledge a message by id
      description: 'msgchannel increment 3. Sets the message read so it stops surfacing as unacked (in list_messages and infrastructure_status''s messages[]). Idempotent: acking an already-acked id returns success with no second effect, never an error.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Acknowledged (or already was — idempotent).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AckMessageResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /messages/contact-operator:
    post:
      operationId: contact_operator
      tags:
      - Messages
      summary: Reach Coldrig support
      description: 'msgchannel Inc5 (founder-ratified 2026-08-11) — the reverse leg: an agent contacting Coldrig support, not the system-or-team-to-agent direction list_messages/ack_message read. Files a support ticket and notifies Coldrig support. Works in every account state an API key still authenticates in, including dunning-suspended, canceling and canceled — this is exactly the channel for "why is my account suspended?". The ONE exception is an admin-TERMINATED (abuse) account: its token is rejected at auth with 401 before this endpoint runs. Coldrig''s reply arrives as a message on THIS account (poll GET /messages or infrastructure_status''s messages[] — there is no separate reply-fetch endpoint). Sending the IDENTICAL body AND urgency again within an hour returns the SAME ticketId and never files a second ticket or sends a second alert — no Idempotency-Key is needed to retry a dropped response. This is a TEXT match, not an intent match: a genuinely new message with coincidentally-identical wording collapses into the earlier ticket the same way a deliberate retry does — vary the wording if you have something new to say. Raising the urgency on the same text is an ESCALATION, not a replay, and does file a new ticket. Rate-limited to 5 calls/hour per account.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactOperatorInput'
      responses:
        '201':
          description: Ticket recorded (or an identical-body dedup hit within the last hour, same ticketId).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactOperatorResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          description: 'More than 5 contact_operator calls from this account in the last hour. `retryAfter` (seconds) names when the window next has room.

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
                  retryAfter:
                    type: integer
                    description: Seconds until this account's rate window has room again.
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /messages/feedback:
    post:
      operationId: submit_feedback
      tags:
      - Messages
      summary: Send private feedback to the Coldrig founders
      description: 'Private product feedback: a 0-10 `score` and/or free `text` (at least one is required). It is stored privately, emailed to the founders and never published; it opens no support ticket and changes nothing on the account (use contact_operator for a problem that needs an answer). Each call is a separate submission.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitFeedbackInput'
      responses:
        '201':
          description: Feedback recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitFeedbackResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
components:
  schemas:
    ContactOperatorInput:
      type: object
      required:
      - body
      properties:
        body:
          type: string
          minLength: 1
          maxLength: 2000
        urgency:
          type: string
          enum:
          - normal
          - needs_human
          default: normal
          description: 'Flags the ops alert/ticket for triage, and `needs_human` also bypasses the ~10-minute ops-email throttle so an urgent message is PUSHED rather than left in the pull-only digest (still bounded by the 5-calls/hour cap). It is part of the dedup identity: the same body re-sent at a higher urgency is an escalation and files a new ticket, not a replay.

            '
    Message:
      type: object
      required:
      - id
      - kind
      - severity
      - body
      - actionHint
      - source
      - createdAt
      - readAt
      properties:
        id:
          type: string
        kind:
          type: string
        severity:
          type: string
          enum:
          - info
          - action_required
          - operator_pending
          - terminal
          description: 'info = resolves on its own, nothing is required. action_required = nothing progresses until you act, and acting works. operator_pending = the platform has stopped and nothing YOU change will restart it, but someone at Coldrig can clear the blocker (e.g. funding a provider account), after which retrying the SAME request with the SAME idempotency key completes it — do not alter your inputs and do not give up. terminal = the platform has stopped; retrying will never help and only Coldrig support can move it (the message''s actionHint names contact_operator).

            '
        body:
          type: string
        actionHint:
          type:
          - object
          - 'null'
        source:
          type: string
          enum:
          - system
          - operator
        createdAt:
          type: integer
        readAt:
          type:
          - integer
          - 'null'
    SubmitFeedbackResult:
      type: object
      required:
      - feedbackId
      - received
      properties:
        feedbackId:
          type: string
        received:
          type: boolean
          enum:
          - true
    ContactOperatorResult:
      type: object
      required:
      - ticketId
      - note
      - deduplicated
      properties:
        ticketId:
          type: string
        note:
          type: string
          description: Tells the caller where Coldrig's reply will surface (list_messages / infrastructure_status.messages[]).
        deduplicated:
          type: boolean
          description: 'true means no new ticket was filed and no new alert was sent — `ticketId` is from an earlier call whose body AND urgency were IDENTICAL, within the last hour. This is a text match, not an intent match: a genuinely new message with the same wording collapses just as silently, so treat `true` as "this exact text was already sent", not as "nothing new happened".

            '
    AckMessageResult:
      type: object
      required:
      - acked
      - alreadyAcked
      properties:
        acked:
          type: boolean
          enum:
          - true
        alreadyAcked:
          type: boolean
    SubmitFeedbackInput:
      type: object
      description: At least one of `score` or `text` is required.
      properties:
        score:
          type: integer
          minimum: 0
          maximum: 10
        text:
          type: string
          minLength: 1
          maxLength: 2000
    MessageListPage:
      type: object
      required:
      - messages
      - nextCursor
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        nextCursor:
          type:
          - string
          - 'null'
  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