Knock Messages API — Messages

naftiko: 1.0.0-alpha2
info:
  label: Knock Messages API — Messages
  description: 'Knock Messages API — Messages. 24 operations. Lead operation: batchmarkmessagesasunarchived. Self-contained Naftiko capability covering one Knock business surface.'
  tags:
  - Knock
  - Messages
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    KNOCK_API_KEY: KNOCK_API_KEY
capability:
  consumes:
  - type: http
    namespace: messages
    baseUri: https://api.knock.app
    description: Knock Knock Messages API business capability. Self-contained, no shared references.
    resources:
    - 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
          required: true
    - name: v1-messages
      path: /v1/messages
      operations:
      - name: listmessages
        method: GET
        description: List messages
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v1-messages-message_id-unseen
      path: /v1/messages/{message_id}/unseen
      operations:
      - name: markmessageunseen (2)
        method: DELETE
        description: Mark message as unseen
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          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
          required: true
    - name: v1-messages-message_id-unread
      path: /v1/messages/{message_id}/unread
      operations:
      - name: markmessageunread (2)
        method: DELETE
        description: Mark message as unread
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          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
          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
          required: true
        - name: body
          in: body
          type: object
          required: true
    - 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
          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
          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
          required: true
    - 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
          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
          required: true
        - name: body
          in: body
          type: object
          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: $.
    - 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
          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
          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
          required: true
    - name: v1-messages-message_id-archived
      path: /v1/messages/{message_id}/archived
      operations:
      - name: unarchivemessage (2)
        method: DELETE
        description: Unarchive message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: message_id
          in: path
          type: string
          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
          required: true
        - name: body
          in: body
          type: object
          required: true
    - 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
          required: true
    - 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
          required: true
        - name: body
          in: body
          type: object
          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
          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
          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
          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
          required: true
    authentication:
      type: bearer
      value: '{{env.KNOCK_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: messages-rest
    port: 8080
    description: REST adapter for Knock Knock Messages API.
    resources:
    - 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: messages.listmessagedeliverylogs
        with:
          message_id: rest.message_id
        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: messages.listmessages
        with: {}
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message_id}/unseen
      name: v1-messages-message_id-unseen
      description: REST surface for v1-messages-message_id-unseen.
      operations:
      - method: DELETE
        name: markmessageunseen (2)
        description: Mark message as unseen
        call: messages.markmessageunseen (2)
        with:
          message_id: rest.message_id
        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: messages.batchmarkmessagesasunarchived
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message_id}/unread
      name: v1-messages-message_id-unread
      description: REST surface for v1-messages-message_id-unread.
      operations:
      - method: DELETE
        name: markmessageunread (2)
        description: Mark message as unread
        call: messages.markmessageunread (2)
        with:
          message_id: rest.message_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message_id}/seen
      name: v1-messages-message_id-seen
      description: REST surface for v1-messages-message_id-seen.
      operations:
      - method: DELETE
        name: markmessageunseen
        description: Mark message as unseen
        call: messages.markmessageunseen
        with:
          message_id: rest.message_id
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: markmessageseen
        description: Mark message as seen
        call: messages.markmessageseen
        with:
          message_id: rest.message_id
          body: rest.body
        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: messages.listmessageevents
        with:
          message_id: rest.message_id
        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: messages.batchmarkmessagesasseen
        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: messages.batchmarkmessagesasunseen
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message_id}/read
      name: v1-messages-message_id-read
      description: REST surface for v1-messages-message_id-read.
      operations:
      - method: DELETE
        name: markmessageunread
        description: Mark message as unread
        call: messages.markmessageunread
        with:
          message_id: rest.message_id
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: markmessageread
        description: Mark message as read
        call: messages.markmessageread
        with:
          message_id: rest.message_id
          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: messages.batchgetmessagecontents
        with: {}
        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: messages.getmessagecontents
        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: messages.listmessageactivities
        with:
          message_id: rest.message_id
        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: messages.batchmarkmessagesasunread
        with:
          body: rest.body
        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: unarchivemessage (2)
        description: Unarchive message
        call: messages.unarchivemessage (2)
        with:
          message_id: rest.message_id
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: archivemessage
        description: Archive message
        call: messages.archivemessage
        with:
          message_id: rest.message_id
          body: rest.body
        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: messages.batchmarkmessagesasarchived
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message_id}/interacted
      name: v1-messages-message_id-interacted
      description: REST surface for v1-messages-message_id-interacted.
      operations:
      - method: PUT
        name: markmessageinteracted
        description: Mark message as interacted
        call: messages.markmessageinteracted
        with:
          message_id: rest.message_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/messages/{message_id}/unarchived
      name: v1-messages-message_id-unarchived
      description: REST surface for v1-messages-message_id-unarchived.
      operations:
      - method: DELETE
        name: unarchivemessage
        description: Unarchive message
        call: messages.unarchivemessage
        with:
          message_id: rest.message_id
        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: messages.batchmarkmessagesasread
        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: messages.getmessage
        with:
          message_id: rest.message_id
        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: messages.batchmarkmessagesasinteracted
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: messages-mcp
    port: 9090
    transport: http
    description: MCP adapter for Knock Knock Messages API. One tool per consumed operation.
    tools:
    - name: knock-listmessagedeliverylogs
      description: List delivery logs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: messages.listmessagedeliverylogs
      with:
        message_id: tools.message_id
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-listmessages
      description: List messages
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: messages.listmessages
      with: {}
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-markmessageunseen (2)
      description: Mark message as unseen
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: messages.markmessageunseen (2)
      with:
        message_id: tools.message_id
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-batchmarkmessagesasunarchived
      description: Mark messages as unarchived
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: messages.batchmarkmessagesasunarchived
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-markmessageunread (2)
      description: Mark message as unread
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: messages.markmessageunread (2)
      with:
        message_id: tools.message_id
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-markmessageunseen
      description: Mark message as unseen
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: messages.markmessageunseen
      with:
        message_id: tools.message_id
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-markmessageseen
      description: Mark message as seen
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: messages.markmessageseen
      with:
        message_id: tools.message_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-listmessageevents
      description: List events
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: messages.listmessageevents
      with:
        message_id: tools.message_id
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-batchmarkmessagesasseen
      description: Mark messages as seen
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: messages.batchmarkmessagesasseen
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-batchmarkmessagesasunseen
      description: Mark messages as unseen
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: messages.batchmarkmessagesasunseen
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-markmessageunread
      description: Mark message as unread
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: messages.markmessageunread
      with:
        message_id: tools.message_id
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-markmessageread
      description: Mark message as read
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: messages.markmessageread
      with:
        message_id: tools.message_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-batchgetmessagecontents
      description: Batch get message contents
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: messages.batchgetmessagecontents
      with: {}
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-getmessagecontents
      description: Get message content
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: messages.getmessagecontents
      with:
        message_id: tools.message_id
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-listmessageactivities
      description: List activities
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: messages.listmessageactivities
      with:
        message_id: tools.message_id
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-batchmarkmessagesasunread
      description: Mark messages as unread
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: messages.batchmarkmessagesasunread
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-unarchivemessage (2)
      description: Unarchive message
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: messages.unarchivemessage (2)
      with:
        message_id: tools.message_id
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-archivemessage
      description: Archive message
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: messages.archivemessage
      with:
        message_id: tools.message_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-batchmarkmessagesasarchived
      description: Mark messages as archived
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: messages.batchmarkmessagesasarchived
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-markmessageinteracted
      description: Mark message as interacted
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: messages.markmessageinteracted
      with:
        message_id: tools.message_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-unarchivemessage
      description: Unarchive message
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: messages.unarchivemessage
      with:
        message_id: tools.message_id
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-batchmarkmessagesasread
      description: Mark messages as read
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: messages.batchmarkmessagesasread
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-getmessage
      description: Get message
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: messages.getmessage
      with:
        message_id: tools.message_id
      outputParameters:
      - type: object
        mapping: $.
    - name: knock-batchmarkmessagesasinteracted
      description: Mark messages as interacted
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: messages.batchmarkmessagesasinteracted
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.