> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lithoblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List sent messages

> Messages LithoBlocks delivered to Slack, newest first, from every send path. Failed sends, which have no Slack message, are not listed. Content is in `GET /messages/{id}`.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/messages
openapi: 3.0.0
info:
  version: 0.0.1
  title: LithoBlocks API
  description: >-

    Manage templates, compile and send Slack messages, schedule delivery, build
    batch digests, and configure interactive workflows.


    Use /v1 paths and snake_case request fields. Authenticate with an
    organization-scoped API key in the Authorization: Bearer header. Each
    operation documents its required scope; a key without it receives 403 and
    required_scopes. A user's organization role limits which scopes a key can
    receive. Compiling and sending require messages:create; read access alone
    does not allow either operation.


    Create and manage keys in Integrations → API Keys. Store credentials in a
    secret manager, grant only the scopes needed, and use separate keys for each
    environment. Resources and credentials do not transfer between environments.


    Use code and request_id to diagnose API errors. The error field can be a
    string or a schema-validation object; consult the endpoint response schema
    for details. Resource list endpoints document their pagination and
    compatibility fields individually.


    See the documentation guides for API key lifecycle, the complete scope/role
    matrix, environment availability, input-schema discovery, and idempotent
    sending. The endpoint definitions below are the source for request and
    response contracts.
                
  contact:
    name: LithoBlocks
    url: https://lithoblocks.com
    email: support@lithoblocks.com
servers:
  - url: https://api.lithoblocks.com
    description: Production (paths in this spec are rooted at /v1/...)
  - url: http://localhost:9999
    description: Local dev (paths in this spec are rooted at /v1/...)
security: []
paths:
  /v1/messages:
    get:
      tags:
        - Messages
      summary: List sent messages
      description: >-
        Messages LithoBlocks delivered to Slack, newest first, from every send
        path. Failed sends, which have no Slack message, are not listed. Content
        is in `GET /messages/{id}`.
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          required: false
          name: limit
          in: query
        - schema:
            type: integer
            nullable: true
            minimum: 0
            default: 0
          required: false
          name: offset
          in: query
        - schema:
            type: string
            format: uuid
          required: false
          name: template_id
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 255
          required: false
          name: channel_id
          in: query
        - schema:
            type: string
            maxLength: 40
            pattern: ^\d+\.\d+$
            description: >-
              Find one message by its Slack timestamp; combine with
              `channel_id`.
          required: false
          description: Find one message by its Slack timestamp; combine with `channel_id`.
          name: message_ts
          in: query
        - schema:
            type: string
            enum:
              - live
              - deleted
              - expired
            description: What has happened to the message in Slack since it was sent.
          required: false
          description: What has happened to the message in Slack since it was sent.
          name: lifecycle
          in: query
        - schema:
            type: string
            enum:
              - api
              - api_bulk
              - web
              - scheduled
              - digest
              - slash
            description: How it was sent. Null for messages sent before 2026-10-22.
          required: false
          description: How it was sent. Null for messages sent before 2026-10-22.
          name: source
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 255
          required: false
          name: reference
          in: query
        - schema:
            type: string
            format: date-time
          required: false
          name: sent_after
          in: query
        - schema:
            type: string
            format: date-time
          required: false
          name: sent_before
          in: query
        - schema:
            type: string
            format: date-time
            description: Messages with a pending expiry before this time.
          required: false
          description: Messages with a pending expiry before this time.
          name: expires_before
          in: query
      responses:
        '200':
          description: Sent messages
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SentMessage'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  total:
                    type: number
                  limit:
                    type: number
                  offset:
                    type: number
                required:
                  - data
                  - pagination
                  - total
                  - limit
                  - offset
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Message not found in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: The request body, query string or path parameters failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth:
            - messages:read
components:
  schemas:
    SentMessage:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: >-
            LithoBlocks' id for the message; send responses return it as
            `message_id`.
        template_id:
          type: string
          nullable: true
          format: uuid
          description: Null once the template has been deleted.
        template_name:
          type: string
          nullable: true
          description: The template's name when the message was sent.
        template_version_id:
          type: string
          nullable: true
          format: uuid
        workspace_id:
          type: string
          description: The Slack workspace (team) id.
        channel_id:
          type: string
          nullable: true
          description: The resolved channel; a `D…` id for a direct message.
        channel_name:
          type: string
          nullable: true
          description: >-
            The channel's name when the message was sent, without the #. Null
            for direct messages, private channels and messages sent before
            2026-10-22.
        message_ts:
          type: string
          description: Slack's timestamp for the message.
        recipient_email:
          type: string
          nullable: true
        recipient_slack_id:
          type: string
          nullable: true
        sent_at:
          type: string
        sent_by:
          type: string
          format: uuid
          description: The user the send is attributed to; for an API key, the key's owner.
        sender_api_key_id:
          type: string
          nullable: true
          format: uuid
        sender_client_id:
          type: string
          nullable: true
          description: The OAuth client a session token was issued to, e.g. an MCP client.
        source:
          type: string
          nullable: true
          enum:
            - api
            - api_bulk
            - web
            - scheduled
            - digest
            - slash
          description: How it was sent. Null for messages sent before 2026-10-22.
        reference:
          type: string
          nullable: true
          description: The caller's own handle for the message, if it gave one.
        lifecycle:
          type: string
          enum:
            - live
            - deleted
            - expired
          description: What has happened to the message in Slack since it was sent.
        revision:
          type: integer
          description: >-
            Increments with every change; a change names the revision it was
            made against.
        edited_at:
          type: string
          nullable: true
        deleted_at:
          type: string
          nullable: true
        expired_at:
          type: string
          nullable: true
        change_state:
          type: string
          enum:
            - idle
            - in_progress
            - needs_reconciliation
          description: >-
            `needs_reconciliation`: Slack's answer to a change was lost, and a
            person must say whether it went through before anything else can
            change.
        pending_action:
          type: string
          nullable: true
          enum:
            - edit
            - rerender
            - interaction_update
            - delete
            - expire
        fallback_text:
          type: string
          nullable: true
          description: The notification text sent with the blocks.
        text_editable:
          type: boolean
          description: >-
            Whether the stored blocks are exactly what Slack holds, so the text
            can be corrected in place.
        expiration:
          $ref: '#/components/schemas/SentMessageExpiration'
      required:
        - id
        - template_id
        - template_name
        - template_version_id
        - workspace_id
        - channel_id
        - channel_name
        - message_ts
        - recipient_email
        - recipient_slack_id
        - sent_at
        - sent_by
        - sender_api_key_id
        - sender_client_id
        - source
        - reference
        - lifecycle
        - revision
        - edited_at
        - deleted_at
        - expired_at
        - change_state
        - pending_action
        - fallback_text
        - text_editable
        - expiration
    Pagination:
      type: object
      properties:
        offset:
          type: integer
          description: Index of the first item in `data`
        limit:
          type: integer
          description: Maximum number of items in `data`
        total:
          type: integer
          description: Total items matching the query
      required:
        - offset
        - limit
        - total
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: Human-readable summary. Not stable; match on `code`.
        code:
          $ref: '#/components/schemas/ErrorCode'
        request_id:
          type: string
          description: >-
            Echoed from the request's X-Request-Id header, or generated. Quote
            it in support requests.
        message:
          type: string
        details:
          type: string
        error_details:
          type: string
        success:
          type: boolean
          enum:
            - false
        valid:
          type: boolean
          enum:
            - false
        required_scopes:
          type: array
          items:
            type: string
        user_scopes:
          type: array
          items:
            type: string
      required:
        - error
        - code
        - request_id
    ValidationError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            issues:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  path:
                    type: array
                    items:
                      anyOf:
                        - type: string
                        - type: number
                  message:
                    type: string
                required:
                  - code
                  - path
                  - message
            name:
              type: string
          required:
            - issues
            - name
        message:
          type: string
          description: >-
            The issues as one line, `path: message; path: message`, for callers
            that show a string (form builders such as Make)
        code:
          type: string
          enum:
            - validation_failed
        request_id:
          type: string
      required:
        - success
        - error
        - message
        - code
        - request_id
    SentMessageExpiration:
      type: object
      nullable: true
      properties:
        expires_at:
          type: string
        mode:
          type: string
          enum:
            - replace
            - delete
          description: >-
            `replace` (default): the message is replaced with a notice that it
            expired, and its buttons stop working. `delete`: it is deleted from
            Slack.
        state:
          type: string
          enum:
            - scheduled
            - processing
            - completed
            - failed
            - cancelled
          description: >-
            `failed`: the expiry gave up after its retries (see `last_error`);
            the message's buttons still do nothing after the deadline.
        retain_content:
          type: boolean
          description: >-
            Whether LithoBlocks keeps its copies of what the message said after
            it expires.
        attempts:
          type: integer
        last_error:
          type: string
          nullable: true
        completed_at:
          type: string
          nullable: true
      required:
        - expires_at
        - mode
        - state
        - retain_content
        - attempts
        - last_error
        - completed_at
      description: The message's expiry, if one was ever set.
    ErrorCode:
      type: string
      enum:
        - unauthenticated
        - invalid_token
        - insufficient_scope
        - access_denied
        - validation_failed
        - invalid_request
        - invalid_data
        - invalid_destination
        - invalid_search_query
        - not_found
        - template_not_found
        - version_not_found
        - organization_not_found
        - entity_not_found
        - field_not_found
        - user_not_found
        - profile_not_found
        - credits_not_found
        - insufficient_credits
        - overage_limit_exceeded
        - credit_deduction_failed
        - compilation_failed
        - no_blocks_to_send
        - slack_not_connected
        - slack_user_not_found
        - slack_dm_failed
        - slack_token_decrypt_failed
        - slack_api_error
        - already_exists
        - invitation_pending
        - idempotency_conflict
        - idempotency_in_progress
        - rate_limited
        - tier_limit
        - invalid_state
        - template_archived
        - template_in_use
        - template_not_activated
        - current_version_changed
        - message_not_found
        - not_message_sender
        - revision_conflict
        - message_not_live
        - mutation_in_progress
        - reconciliation_required
        - nothing_to_reconcile
        - text_not_editable
        - slack_refused
        - slack_outcome_unknown
        - expiration_in_past
        - expiration_in_progress
        - no_expiration
        - expiration_exceeds_maximum
        - maintenance
        - misconfigured
        - internal_error
      description: >-
        Machine-readable reason for the failure. Match on this, not on `error`.
        New codes may be added; existing ones are stable.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        LithoBlocks API key obtained from your organization dashboard. The
        LithoBlocks MCP server also presents a Supabase-issued user session
        token here on the user's behalf; such a token acts as that user with the
        scopes their organization role allows.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.