Knock API — Messages

naftiko: 1.0.0-alpha2
info:
  label: Knock API — Messages
  description: 'Knock API — Messages. 27 operations. Lead operation: Bulk update message statuses for channel. Self-contained
    Naftiko capability covering one Knock business surface.'
  tags:
  - Knock
  - Messages
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    KNOCK_API_KEY: KNOCK_API_KEY
capability:
  consumes:
  - type: http
    namespace: knock-messages
    baseUri: https://api.knock.app
    description: Knock API — Messages business capability. Self-contained, no shared references.
    resources:
    - name: v1-channels-channel_id-messages-bulk-action
      path: /v1/channels/{channel_id}/messages/bulk/{action}
      operations:
      - name: bulkupdatemessagesforchannel
        method: POST
        description: Bulk update message statuses for channel
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: channel_id
          in: path
          type: string
          description: The ID of the channel to update messages for.
          required: true
        - name: action
          in: path
          type: string
          description: The target status to be applied to the messages.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v1-messages
      path: /v1/messages
      operations:
      - name: listmessages
        method: GET
        description: List messages
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: after
          in: query
          type: string
          description: The cursor to fetch entries after.
        - name: before
          in: query
          type: string
          description: The cursor to fetch entries before.
        - name: page_size
          in: query
          type: integer
          description: The number of items per page (defaults to 50).
        - name: tenant
          in: query
          type: string
          description: Limits the results to items with the corresponding tenant.
        - name: channel_id
          in: query
          type: string
          description: Limits the results to items with the corresponding channel ID.
        - name: status[]
          in: query
          type: array
          description: Limits the results to messages with the given delivery status.
        - name: engagement_status[]
          in: query
          type: array
          description: Limits the results to messages with the given engagement status.
        - name: message_ids[]
          in: query
          type: array
          description: 'Limits the results to only the message IDs given (max 50). Note: when using this option, the results
            will be subject to any other filters applied to the query.'
        - name: workflow_categories[]
          in: query
          type: array
          description: Limits the results to messages related to any of the provided categories.
        - name: source
          in: query
          type: string
          description: Limits the results to messages triggered by the given workflow key.
        - name: workflow_run_id
          in: query
          type: string
          description: Limits the results to messages associated with the top-level workflow run ID returned by the workflow
            trigger request.
        - name: workflow_recipient_run_id
          in: query
          type: string
          description: Limits the results to messages for a specific recipient's workflow run.
        - name: trigger_data
          in: query
          type: string
          description: Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering)
            for mo
        - name: inserted_at.gt
          in: query
          type: string
          description: Limits the results to items inserted after the given date.
        - name: inserted_at.gte
          in: query
          type: string
          description: Limits the results to items inserted after or on the given date.
        - name: inserted_at.lt
          in: query
          type: string
          description: Limits the results to items inserted before the given date.
        - name: inserted_at.lte
          in: query
          type: string
          description: Limits the results to items inserted before or on the given date.
    - name: v1-messages-batch-archived
      path: /v1/messages/batch/archived
      operations:
      - name: batchmarkmessagesasarchived
        method: POST
        description: Mark messages as archived
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v1-messages-batch-content
      path: /v1/messages/batch/content
      operations:
      - name: batchgetmessagecontents
        method: GET
        description: Batch get message contents
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_ids[]
          in: query
          type: array
          description: The IDs of the messages to fetch contents of.
          required: true
    - name: v1-messages-batch-interacted
      path: /v1/messages/batch/interacted
      operations:
      - name: batchmarkmessagesasinteracted
        method: POST
        description: Mark messages as interacted
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v1-messages-batch-read
      path: /v1/messages/batch/read
      operations:
      - name: batchmarkmessagesasread
        method: POST
        description: Mark messages as read
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v1-messages-batch-seen
      path: /v1/messages/batch/seen
      operations:
      - name: batchmarkmessagesasseen
        method: POST
        description: Mark messages as seen
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v1-messages-batch-unarchived
      path: /v1/messages/batch/unarchived
      operations:
      - name: batchmarkmessagesasunarchived
        method: POST
        description: Mark messages as unarchived
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v1-messages-batch-unread
      path: /v1/messages/batch/unread
      operations:
      - name: batchmarkmessagesasunread
        method: POST
        description: Mark messages as unread
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v1-messages-batch-unseen
      path: /v1/messages/batch/unseen
      operations:
      - name: batchmarkmessagesasunseen
        method: POST
        description: Mark messages as unseen
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v1-messages-message_id
      path: /v1/messages/{message_id}
      operations:
      - name: getmessage
        method: GET
        description: Get message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The unique identifier for the message.
          required: true
    - name: v1-messages-message_id-activities
      path: /v1/messages/{message_id}/activities
      operations:
      - name: listmessageactivities
        method: GET
        description: List activities
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The ID of the message to fetch activities for.
          required: true
        - name: trigger_data
          in: query
          type: string
          description: The trigger data to filter activities by.
        - name: after
          in: query
          type: string
          description: The cursor to fetch entries after.
        - name: before
          in: query
          type: string
          description: The cursor to fetch entries before.
        - name: page_size
          in: query
          type: integer
          description: The number of items per page (defaults to 50).
    - name: v1-messages-message_id-archived
      path: /v1/messages/{message_id}/archived
      operations:
      - name: unarchivemessage2
        method: DELETE
        description: Unarchive message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The unique identifier for the message.
          required: true
      - name: archivemessage
        method: PUT
        description: Archive message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The unique identifier for the message.
          required: true
    - name: v1-messages-message_id-content
      path: /v1/messages/{message_id}/content
      operations:
      - name: getmessagecontents
        method: GET
        description: Get message content
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The ID of the message to fetch contents of.
          required: true
    - name: v1-messages-message_id-delivery_logs
      path: /v1/messages/{message_id}/delivery_logs
      operations:
      - name: listmessagedeliverylogs
        method: GET
        description: List delivery logs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The ID of the message to fetch delivery logs for.
          required: true
        - name: after
          in: query
          type: string
          description: The cursor to fetch entries after.
        - name: before
          in: query
          type: string
          description: The cursor to fetch entries before.
        - name: page_size
          in: query
          type: integer
          description: The number of items per page (defaults to 50).
    - name: v1-messages-message_id-events
      path: /v1/messages/{message_id}/events
      operations:
      - name: listmessageevents
        method: GET
        description: List events
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The ID of the message to fetch events for.
          required: true
        - name: after
          in: query
          type: string
          description: The cursor to fetch entries after.
        - name: before
          in: query
          type: string
          description: The cursor to fetch entries before.
        - name: page_size
          in: query
          type: integer
          description: The number of items per page (defaults to 50).
    - name: v1-messages-message_id-interacted
      path: /v1/messages/{message_id}/interacted
      operations:
      - name: markmessageinteracted
        method: PUT
        description: Mark message as interacted
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The unique identifier for the message.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-messages-message_id-read
      path: /v1/messages/{message_id}/read
      operations:
      - name: markmessageunread
        method: DELETE
        description: Mark message as unread
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The unique identifier for the message.
          required: true
      - name: markmessageread
        method: PUT
        description: Mark message as read
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The unique identifier for the message.
          required: true
    - name: v1-messages-message_id-seen
      path: /v1/messages/{message_id}/seen
      operations:
      - name: markmessageunseen
        method: DELETE
        description: Mark message as unseen
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The unique identifier for the message.
          required: true
      - name: markmessageseen
        method: PUT
        description: Mark message as seen
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The unique identifier for the message.
          required: true
    - name: v1-messages-message_id-unarchived
      path: /v1/messages/{message_id}/unarchived
      operations:
      - name: unarchivemessage
        method: DELETE
        description: Unarchive message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The unique identifier for the message.
          required: true
    - name: v1-messages-message_id-unread
      path: /v1/messages/{message_id}/unread
      operations:
      - name: markmessageunread2
        method: DELETE
        description: Mark message as unread
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The unique identifier for the message.
          required: true
    - name: v1-messages-message_id-unseen
      path: /v1/messages/{message_id}/unseen
      operations:
      - name: markmessageunseen2
        method: DELETE
        description: Mark message as unseen
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          description: The unique identifier for the message.
          required: true
    - name: v1-objects-collection-id-messages
      path: /v1/objects/{collection}/{id}/messages
      operations:
      - name: listmessagesforobject
        method: GET
        description: List messages
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: after
          in: query
          type: string
          description: The cursor to fetch entries after.
        - name: before
          in: query
          type: string
          description: The cursor to fetch entries before.
        - name: page_size
          in: query
          type: integer
          description: The number of items per page (defaults to 50).
        - name: tenant
          in: query
          type: string
          description: Limits the results to items with the corresponding tenant.
        - name: channel_id
          in: query
          type: string
          description: Limits the results to items with the corresponding channel ID.
        - name: status[]
          in: query
          type: array
          description: Limits the results to messages with the given delivery status.
        - name: engagement_status[]
          in: query
          type: array
          description: Limits the results to messages with the given engagement status.
        - name: message_ids[]
          in: query
          type: array
          description: 'Limits the results to only the message IDs given (max 50). Note: when using this option, the results
            will be subject to any other filters applied to the query.'
        - name: workflow_categories[]
          in: query
          type: array
          description: Limits the results to messages related to any of the provided categories.
        - name: source
          in: query
          type: string
          description: Limits the results to messages triggered by the given workflow key.
        - name: workflow_run_id
          in: query
          type: string
          description: Limits the results to messages associated with the top-level workflow run ID returned by the workflow
            trigger request.
        - name: workflow_recipient_run_id
          in: query
          type: string
          description: Limits the results to messages for a specific recipient's workflow run.
        - name: trigger_data
          in: query
          type: string
          description: Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering)
            for mo
        - name: inserted_at.gt
          in: query
          type: string
          description: Limits the results to items inserted after the given date.
        - name: inserted_at.gte
          in: query
          type: string
          description: Limits the results to items inserted after or on the given date.
        - name: inserted_at.lt
          in: query
          type: string
          description: Limits the results to items inserted before the given date.
        - name: inserted_at.lte
          in: query
          type: string
          description: Limits the results to items inserted before or on the given date.
        - name: collection
          in: path
          type: string
          description: The collection this object belongs to.
          required: true
        - name: id
          in: path
          type: string
          description: Unique identifier for the object.
          required: true
    - name: v1-users-user_id-messages
      path: /v1/users/{user_id}/messages
      operations:
      - name: listmessagesforuser
        method: GET
        description: List user messages
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: after
          in: query
          type: string
          description: The cursor to fetch entries after.
        - name: before
          in: query
          type: string
          description: The cursor to fetch entries before.
        - name: page_size
          in: query
          type: integer
          description: The number of items per page (defaults to 50).
        - name: tenant
          in: query
          type: string
          description: Limits the results to items with the corresponding tenant.
        - name: channel_id
          in: query
          type: string
          description: Limits the results to items with the corresponding channel ID.
        - name: status[]
          in: query
          type: array
          description: Limits the results to messages with the given delivery status.
        - name: engagement_status[]
          in: query
          type: array
          description: Limits the results to messages with the given engagement status.
        - name: message_ids[]
          in: query
          type: array
          description: 'Limits the results to only the message IDs given (max 50). Note: when using this option, the results
            will be subject to any other filters applied to the query.'
        - name: workflow_categories[]
          in: query
          type: array
          description: Limits the results to messages related to any of the provided categories.
        - name: source
          in: query
          type: string
          description: Limits the results to messages triggered by the given workflow key.
        - name: workflow_run_id
          in: query
          type: string
          description: Limits the results to messages associated with the top-level workflow run ID returned by the workflow
            trigger request.
        - name: workflow_recipient_run_id
          in: query
          type: string
          description: Limits the results to messages for a specific recipient's workflow run.
        - name: trigger_data
          in: query
          type: string
          description: Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering)
            for mo
        - name: inserted_at.gt
          in: query
          type: string
          description: Limits the results to items inserted after the given date.
        - name: inserted_at.gte
          in: query
          type: string
          description: Limits the results to items inserted after or on the given date.
        - name: inserted_at.lt
          in: query
          type: string
          description: Limits the results to items inserted before the given date.
        - name: inserted_at.lte
          in: query
          type: string
          description: Limits the results to items inserted before or on the given date.
        - name: user_id
          in: path
          type: string
          description: The user ID to list messages for.
          required: true
    authentication:
      type: bearer
      token: '{{env.KNOCK_API_KEY}}'
  exposes:
  - type: rest
    namespace: knock-messages-rest
    port: 8080
    description: REST adapter for Knock API — Messages. One Spectral-compliant resource per consumed operation, prefixed with
      /v1.
    resources:
    - path: /v1/v1/channels/{channel-id}/messages/bulk/{action}
      name: v1-channels-channel-id-messages-bulk-action
      description: REST surface for v1-channels-channel_id-messages-bulk-action.
      operations:
      - method: POST
        name: bulkupdatemessagesforchannel
        description: Bulk update message statuses for channel
        call: knock-messages.bulkupdatemessagesforchannel
        with:
          channel_id: rest.channel_id
          action: rest.action
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages
      name: v1-messages
      description: REST surface for v1-messages.
      operations:
      - method: GET
        name: listmessages
        description: List messages
        call: knock-messages.listmessages
        with:
          after: rest.after
          before: rest.before
          page_size: rest.page_size
          tenant: rest.tenant
          channel_id: rest.channel_id
          status[]: rest.status[]
          engagement_status[]: rest.engagement_status[]
          message_ids[]: rest.message_ids[]
          workflow_categories[]: rest.workflow_categories[]
          source: rest.source
          workflow_run_id: rest.workflow_run_id
          workflow_recipient_run_id: rest.workflow_recipient_run_id
          trigger_data: rest.trigger_data
          inserted_at.gt: rest.inserted_at.gt
          inserted_at.gte: rest.inserted_at.gte
          inserted_at.lt: rest.inserted_at.lt
          inserted_at.lte: rest.inserted_at.lte
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/batch/archived
      name: v1-messages-batch-archived
      description: REST surface for v1-messages-batch-archived.
      operations:
      - method: POST
        name: batchmarkmessagesasarchived
        description: Mark messages as archived
        call: knock-messages.batchmarkmessagesasarchived
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/batch/content
      name: v1-messages-batch-content
      description: REST surface for v1-messages-batch-content.
      operations:
      - method: GET
        name: batchgetmessagecontents
        description: Batch get message contents
        call: knock-messages.batchgetmessagecontents
        with:
          message_ids[]: rest.message_ids[]
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/batch/interacted
      name: v1-messages-batch-interacted
      description: REST surface for v1-messages-batch-interacted.
      operations:
      - method: POST
        name: batchmarkmessagesasinteracted
        description: Mark messages as interacted
        call: knock-messages.batchmarkmessagesasinteracted
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/batch/read
      name: v1-messages-batch-read
      description: REST surface for v1-messages-batch-read.
      operations:
      - method: POST
        name: batchmarkmessagesasread
        description: Mark messages as read
        call: knock-messages.batchmarkmessagesasread
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/batch/seen
      name: v1-messages-batch-seen
      description: REST surface for v1-messages-batch-seen.
      operations:
      - method: POST
        name: batchmarkmessagesasseen
        description: Mark messages as seen
        call: knock-messages.batchmarkmessagesasseen
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/batch/unarchived
      name: v1-messages-batch-unarchived
      description: REST surface for v1-messages-batch-unarchived.
      operations:
      - method: POST
        name: batchmarkmessagesasunarchived
        description: Mark messages as unarchived
        call: knock-messages.batchmarkmessagesasunarchived
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/batch/unread
      name: v1-messages-batch-unread
      description: REST surface for v1-messages-batch-unread.
      operations:
      - method: POST
        name: batchmarkmessagesasunread
        description: Mark messages as unread
        call: knock-messages.batchmarkmessagesasunread
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/batch/unseen
      name: v1-messages-batch-unseen
      description: REST surface for v1-messages-batch-unseen.
      operations:
      - method: POST
        name: batchmarkmessagesasunseen
        description: Mark messages as unseen
        call: knock-messages.batchmarkmessagesasunseen
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message-id}
      name: v1-messages-message-id
      description: REST surface for v1-messages-message_id.
      operations:
      - method: GET
        name: getmessage
        description: Get message
        call: knock-messages.getmessage
        with:
          message_id: rest.message_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message-id}/activities
      name: v1-messages-message-id-activities
      description: REST surface for v1-messages-message_id-activities.
      operations:
      - method: GET
        name: listmessageactivities
        description: List activities
        call: knock-messages.listmessageactivities
        with:
          message_id: rest.message_id
          trigger_data: rest.trigger_data
          after: rest.after
          before: rest.before
          page_size: rest.page_size
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message-id}/archived
      name: v1-messages-message-id-archived
      description: REST surface for v1-messages-message_id-archived.
      operations:
      - method: DELETE
        name: unarchivemessage2
        description: Unarchive message
        call: knock-messages.unarchivemessage2
        with:
          message_id: rest.message_id
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: archivemessage
        description: Archive message
        call: knock-messages.archivemessage
        with:
          message_id: rest.message_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message-id}/content
      name: v1-messages-message-id-content
      description: REST surface for v1-messages-message_id-content.
      operations:
      - method: GET
        name: getmessagecontents
        description: Get message content
        call: knock-messages.getmessagecontents
        with:
          message_id: rest.message_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message-id}/delivery-logs
      name: v1-messages-message-id-delivery-logs
      description: REST surface for v1-messages-message_id-delivery_logs.
      operations:
      - method: GET
        name: listmessagedeliverylogs
        description: List delivery logs
        call: knock-messages.listmessagedeliverylogs
        with:
          message_id: rest.message_id
          after: rest.after
          before: rest.before
          page_size: rest.page_size
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message-id}/events
      name: v1-messages-message-id-events
      description: REST surface for v1-messages-message_id-events.
      operations:
      - method: GET
        name: listmessageevents
        description: List events
        call: knock-messages.listmessageevents
        with:
          message_id: rest.mes

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/knock/refs/heads/main/capabilities/knock-messages.yaml