Zulip REST API — messages

naftiko: 1.0.0-alpha2
info:
  label: Zulip REST API — messages
  description: 'Zulip REST API — messages. 20 operations. Lead operation: Mark all messages as read. Self-contained Naftiko
    capability covering one Zulip business surface.'
  tags:
  - Zulip
  - messages
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    ZULIP_API_KEY: ZULIP_API_KEY
capability:
  consumes:
  - type: http
    namespace: zulip-messages
    baseUri: https://{subdomain}.zulipchat.com/api/v1
    description: Zulip REST API — messages business capability. Self-contained, no shared references.
    resources:
    - name: mark_all_as_read
      path: /mark_all_as_read
      operations:
      - name: markallasread
        method: POST
        description: Mark all messages as read
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: mark_stream_as_read
      path: /mark_stream_as_read
      operations:
      - name: markstreamasread
        method: POST
        description: Mark messages in a channel as read
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: mark_topic_as_read
      path: /mark_topic_as_read
      operations:
      - name: marktopicasread
        method: POST
        description: Mark messages in a topic as read
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: messages
      path: /messages
      operations:
      - name: getmessages
        method: GET
        description: Get messages
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: anchor
          in: query
          type: string
          description: Integer message ID to anchor fetching of new messages. Supports special
        - name: include_anchor
          in: query
          type: boolean
          description: Whether a message with the specified ID matching the narrow
        - name: anchor_date
          in: query
          type: string
          description: The date or datetime to use for finding the anchor message when `anchor` is
        - name: num_before
          in: query
          type: integer
          description: The number of messages with IDs less than the anchor to retrieve.
        - name: num_after
          in: query
          type: integer
          description: The number of messages with IDs greater than the anchor to retrieve.
        - name: narrow
          in: query
          type: string
          description: The narrow where you want to fetch the messages from. See how to
        - name: apply_markdown
          in: query
          type: boolean
          description: If `true`, message content is returned in the rendered HTML
        - name: use_first_unread_anchor
          in: query
          type: boolean
          description: 'Legacy way to specify `"anchor": "first_unread"` in Zulip 2.1.x and older.'
        - name: message_ids
          in: query
          type: string
          description: A list of message IDs to fetch. The server will return messages corresponding to the
        - name: allow_empty_topic_name
          in: query
          type: boolean
          description: Whether the client supports processing the empty string as a topic in the
      - name: sendmessage
        method: POST
        description: Send a message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: messages-flags
      path: /messages/flags
      operations:
      - name: updatemessageflags
        method: POST
        description: Update personal message flags
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: messages-flags-narrow
      path: /messages/flags/narrow
      operations:
      - name: updatemessageflagsfornarrow
        method: POST
        description: Update personal message flags for narrow
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: messages-matches_narrow
      path: /messages/matches_narrow
      operations:
      - name: checkmessagesmatchnarrow
        method: GET
        description: Check if messages match a narrow
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: msg_ids
          in: query
          type: string
          description: List of IDs for the messages to check.
          required: true
        - name: narrow
          in: query
          type: string
          description: A structure defining the narrow to check against. See how to
          required: true
    - name: messages-render
      path: /messages/render
      operations:
      - name: rendermessage
        method: POST
        description: Render a message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: messages-message_id
      path: /messages/{message_id}
      operations:
      - name: getmessage
        method: GET
        description: Fetch a single message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: apply_markdown
          in: query
          type: boolean
          description: If `true`, message content is returned in the rendered HTML
        - name: allow_empty_topic_name
          in: query
          type: boolean
          description: Whether the client supports processing the empty string as a topic in the
      - name: updatemessage
        method: PATCH
        description: Edit a message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: deletemessage
        method: DELETE
        description: Delete a message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: messages-message_id-history
      path: /messages/{message_id}/history
      operations:
      - name: getmessagehistory
        method: GET
        description: Get a message's edit history
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: allow_empty_topic_name
          in: query
          type: boolean
          description: Whether the topic names i.e. `topic` and `prev_topic` fields in
    - name: messages-message_id-reactions
      path: /messages/{message_id}/reactions
      operations:
      - name: addreaction
        method: POST
        description: Add an emoji reaction
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: removereaction
        method: DELETE
        description: Remove an emoji reaction
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: messages-message_id-read_receipts
      path: /messages/{message_id}/read_receipts
      operations:
      - name: getreadreceipts
        method: GET
        description: Get a message's read receipts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: messages-message_id-report
      path: /messages/{message_id}/report
      operations:
      - name: reportmessage
        method: POST
        description: Report a message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: thumbnail-status-realm_id_str-filename
      path: /thumbnail/status/{realm_id_str}/{filename}
      operations:
      - name: checkthumbnailstatus
        method: GET
        description: Check thumbnail status
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: realm_id_str
          in: path
          type: integer
          description: The realm ID component of the file's `path_id`. If the `path_id` is
          required: true
        - name: filename
          in: path
          type: string
          description: The file path component of the file's `path_id` (everything
          required: true
    - name: user_uploads
      path: /user_uploads
      operations:
      - name: uploadfile
        method: POST
        description: Upload a file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: user_uploads-realm_id_str-filename
      path: /user_uploads/{realm_id_str}/{filename}
      operations:
      - name: getfiletemporaryurl
        method: GET
        description: Get public temporary URL for an uploaded file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: realm_id_str
          in: path
          type: integer
          description: The realm ID component of the file's `path_id`. If the `path_id` is
          required: true
        - name: filename
          in: path
          type: string
          description: The file path component of the file's `path_id` (everything
          required: true
    authentication:
      type: basic
      username: '{{env.ZULIP_USER}}'
      password: '{{env.ZULIP_PASS}}'
  exposes:
  - type: rest
    namespace: zulip-messages-rest
    port: 8080
    description: REST adapter for Zulip REST API — messages. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/mark-all-as-read
      name: mark-all-as-read
      description: REST surface for mark_all_as_read.
      operations:
      - method: POST
        name: markallasread
        description: Mark all messages as read
        call: zulip-messages.markallasread
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/mark-stream-as-read
      name: mark-stream-as-read
      description: REST surface for mark_stream_as_read.
      operations:
      - method: POST
        name: markstreamasread
        description: Mark messages in a channel as read
        call: zulip-messages.markstreamasread
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/mark-topic-as-read
      name: mark-topic-as-read
      description: REST surface for mark_topic_as_read.
      operations:
      - method: POST
        name: marktopicasread
        description: Mark messages in a topic as read
        call: zulip-messages.marktopicasread
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/messages
      name: messages
      description: REST surface for messages.
      operations:
      - method: GET
        name: getmessages
        description: Get messages
        call: zulip-messages.getmessages
        with:
          anchor: rest.anchor
          include_anchor: rest.include_anchor
          anchor_date: rest.anchor_date
          num_before: rest.num_before
          num_after: rest.num_after
          narrow: rest.narrow
          apply_markdown: rest.apply_markdown
          use_first_unread_anchor: rest.use_first_unread_anchor
          message_ids: rest.message_ids
          allow_empty_topic_name: rest.allow_empty_topic_name
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: sendmessage
        description: Send a message
        call: zulip-messages.sendmessage
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/messages/flags
      name: messages-flags
      description: REST surface for messages-flags.
      operations:
      - method: POST
        name: updatemessageflags
        description: Update personal message flags
        call: zulip-messages.updatemessageflags
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/messages/flags/narrow
      name: messages-flags-narrow
      description: REST surface for messages-flags-narrow.
      operations:
      - method: POST
        name: updatemessageflagsfornarrow
        description: Update personal message flags for narrow
        call: zulip-messages.updatemessageflagsfornarrow
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/messages/matches-narrow
      name: messages-matches-narrow
      description: REST surface for messages-matches_narrow.
      operations:
      - method: GET
        name: checkmessagesmatchnarrow
        description: Check if messages match a narrow
        call: zulip-messages.checkmessagesmatchnarrow
        with:
          msg_ids: rest.msg_ids
          narrow: rest.narrow
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/messages/render
      name: messages-render
      description: REST surface for messages-render.
      operations:
      - method: POST
        name: rendermessage
        description: Render a message
        call: zulip-messages.rendermessage
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/messages/{message-id}
      name: messages-message-id
      description: REST surface for messages-message_id.
      operations:
      - method: GET
        name: getmessage
        description: Fetch a single message
        call: zulip-messages.getmessage
        with:
          apply_markdown: rest.apply_markdown
          allow_empty_topic_name: rest.allow_empty_topic_name
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: updatemessage
        description: Edit a message
        call: zulip-messages.updatemessage
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deletemessage
        description: Delete a message
        call: zulip-messages.deletemessage
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/messages/{message-id}/history
      name: messages-message-id-history
      description: REST surface for messages-message_id-history.
      operations:
      - method: GET
        name: getmessagehistory
        description: Get a message's edit history
        call: zulip-messages.getmessagehistory
        with:
          allow_empty_topic_name: rest.allow_empty_topic_name
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/messages/{message-id}/reactions
      name: messages-message-id-reactions
      description: REST surface for messages-message_id-reactions.
      operations:
      - method: POST
        name: addreaction
        description: Add an emoji reaction
        call: zulip-messages.addreaction
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: removereaction
        description: Remove an emoji reaction
        call: zulip-messages.removereaction
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/messages/{message-id}/read-receipts
      name: messages-message-id-read-receipts
      description: REST surface for messages-message_id-read_receipts.
      operations:
      - method: GET
        name: getreadreceipts
        description: Get a message's read receipts
        call: zulip-messages.getreadreceipts
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/messages/{message-id}/report
      name: messages-message-id-report
      description: REST surface for messages-message_id-report.
      operations:
      - method: POST
        name: reportmessage
        description: Report a message
        call: zulip-messages.reportmessage
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/thumbnail/status/{realm-id-str}/{filename}
      name: thumbnail-status-realm-id-str-filename
      description: REST surface for thumbnail-status-realm_id_str-filename.
      operations:
      - method: GET
        name: checkthumbnailstatus
        description: Check thumbnail status
        call: zulip-messages.checkthumbnailstatus
        with:
          realm_id_str: rest.realm_id_str
          filename: rest.filename
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/user-uploads
      name: user-uploads
      description: REST surface for user_uploads.
      operations:
      - method: POST
        name: uploadfile
        description: Upload a file
        call: zulip-messages.uploadfile
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/user-uploads/{realm-id-str}/{filename}
      name: user-uploads-realm-id-str-filename
      description: REST surface for user_uploads-realm_id_str-filename.
      operations:
      - method: GET
        name: getfiletemporaryurl
        description: Get public temporary URL for an uploaded file
        call: zulip-messages.getfiletemporaryurl
        with:
          realm_id_str: rest.realm_id_str
          filename: rest.filename
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: zulip-messages-mcp
    port: 9090
    transport: http
    description: MCP adapter for Zulip REST API — messages. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: mark-all-messages-read
      description: Mark all messages as read
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: zulip-messages.markallasread
      outputParameters:
      - type: object
        mapping: $.
    - name: mark-messages-channel-read
      description: Mark messages in a channel as read
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: zulip-messages.markstreamasread
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: mark-messages-topic-read
      description: Mark messages in a topic as read
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: zulip-messages.marktopicasread
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-messages
      description: Get messages
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: zulip-messages.getmessages
      with:
        anchor: tools.anchor
        include_anchor: tools.include_anchor
        anchor_date: tools.anchor_date
        num_before: tools.num_before
        num_after: tools.num_after
        narrow: tools.narrow
        apply_markdown: tools.apply_markdown
        use_first_unread_anchor: tools.use_first_unread_anchor
        message_ids: tools.message_ids
        allow_empty_topic_name: tools.allow_empty_topic_name
      outputParameters:
      - type: object
        mapping: $.
    - name: send-message
      description: Send a message
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: zulip-messages.sendmessage
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: update-personal-message-flags
      description: Update personal message flags
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: zulip-messages.updatemessageflags
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: update-personal-message-flags-narrow
      description: Update personal message flags for narrow
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: zulip-messages.updatemessageflagsfornarrow
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: check-if-messages-match-narrow
      description: Check if messages match a narrow
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: zulip-messages.checkmessagesmatchnarrow
      with:
        msg_ids: tools.msg_ids
        narrow: tools.narrow
      outputParameters:
      - type: object
        mapping: $.
    - name: render-message
      description: Render a message
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: zulip-messages.rendermessage
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: fetch-single-message
      description: Fetch a single message
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: zulip-messages.getmessage
      with:
        apply_markdown: tools.apply_markdown
        allow_empty_topic_name: tools.allow_empty_topic_name
      outputParameters:
      - type: object
        mapping: $.
    - name: edit-message
      description: Edit a message
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: zulip-messages.updatemessage
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-message
      description: Delete a message
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: zulip-messages.deletemessage
      outputParameters:
      - type: object
        mapping: $.
    - name: get-message-s-edit-history
      description: Get a message's edit history
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: zulip-messages.getmessagehistory
      with:
        allow_empty_topic_name: tools.allow_empty_topic_name
      outputParameters:
      - type: object
        mapping: $.
    - name: add-emoji-reaction
      description: Add an emoji reaction
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: zulip-messages.addreaction
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: remove-emoji-reaction
      description: Remove an emoji reaction
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: zulip-messages.removereaction
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-message-s-read-receipts
      description: Get a message's read receipts
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: zulip-messages.getreadreceipts
      outputParameters:
      - type: object
        mapping: $.
    - name: report-message
      description: Report a message
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: zulip-messages.reportmessage
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: check-thumbnail-status
      description: Check thumbnail status
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: zulip-messages.checkthumbnailstatus
      with:
        realm_id_str: tools.realm_id_str
        filename: tools.filename
      outputParameters:
      - type: object
        mapping: $.
    - name: upload-file
      description: Upload a file
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: zulip-messages.uploadfile
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-public-temporary-url-uploaded
      description: Get public temporary URL for an uploaded file
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: zulip-messages.getfiletemporaryurl
      with:
        realm_id_str: tools.realm_id_str
        filename: tools.filename
      outputParameters:
      - type: object
        mapping: $.