Slack Search API

openapi: 3.2.0
info:
  title: Slack Web Search API
  description: The Slack Web API is an HTTP-based interface that provides access to all of Slack's platform features. It consists of over 200 methods organized by functional area (chat, conversations, users, files, admin, and more) that apps call over HTTPS with JSON payloads and receive JSON responses. All methods require authentication via OAuth tokens (bot or user) with granular permission scopes, and are subject to tiered rate limits. The Web API supports cursor-based pagination for large result sets and provides consistent error handling across all endpoints.
  version: 1.0.0
  termsOfService: https://slack.com/terms-of-service/api
  contact:
    name: Slack Developer Support
    url: https://docs.slack.dev
  license:
    name: Slack API Terms of Service
    url: https://slack.com/terms-of-service/api
servers:
- url: https://slack.com/api
  description: Slack Web API production server
security:
- bearerAuth: []
tags:
- name: Search
  description: Search messages and files
paths:
  /search.messages:
    get:
      tags:
      - Search
      summary: Slack Search for Messages
      description: Searches for messages matching a query. Supports Slack search modifiers such as in:, from:, has:, before:, after:, and is:thread.
      operationId: searchMessages
      externalDocs:
        description: API method documentation
        url: https://docs.slack.dev/reference/methods/search.messages
      parameters:
      - name: query
        in: query
        required: true
        description: Search query.
        schema:
          type: string
      - name: count
        in: query
        schema:
          type: integer
          default: 20
      - name: highlight
        in: query
        description: Pass a value of true to enable query highlight markers.
        schema:
          type: boolean
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: sort
        in: query
        description: Return matches sorted by either score or timestamp.
        schema:
          type: string
          enum:
          - score
          - timestamp
      - name: sort_dir
        in: query
        description: Change sort direction to ascending or descending.
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Search results returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  query:
                    type: string
                  messages:
                    type: object
                    properties:
                      total:
                        type: integer
                      pagination:
                        type: object
                        properties:
                          total_count:
                            type: integer
                          page:
                            type: integer
                          per_page:
                            type: integer
                          page_count:
                            type: integer
                          first:
                            type: integer
                          last:
                            type: integer
                      paging:
                        type: object
                        properties:
                          count:
                            type: integer
                          total:
                            type: integer
                          page:
                            type: integer
                          pages:
                            type: integer
                      matches:
                        type: array
                        items:
                          $ref: '#/components/schemas/Message'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /search.files:
    get:
      tags:
      - Search
      summary: Slack Search for Files
      description: Searches for files matching a query.
      operationId: searchFiles
      externalDocs:
        description: API method documentation
        url: https://docs.slack.dev/reference/methods/search.files
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
      - name: count
        in: query
        schema:
          type: integer
          default: 20
      - name: highlight
        in: query
        schema:
          type: boolean
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - score
          - timestamp
      - name: sort_dir
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Search results returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  query:
                    type: string
                  files:
                    type: object
                    properties:
                      total:
                        type: integer
                      matches:
                        type: array
                        items:
                          $ref: '#/components/schemas/File'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    File:
      type: object
      description: A Slack file object representing an uploaded file with its metadata and sharing information.
      properties:
        id:
          type: string
          description: Unique file identifier.
          example: abc123
        created:
          type: integer
          description: Unix timestamp of when the file was created.
          example: 10
        timestamp:
          type: integer
          description: Unix timestamp.
          example: 10
        name:
          type: string
          description: The file name.
          example: Example Title
        title:
          type: string
          description: Title of the file.
          example: Example Title
        mimetype:
          type: string
          description: MIME type of the file.
          example: example_value
        filetype:
          type: string
          description: Slack file type identifier (e.g., "png", "pdf", "snippet").
          example: example_value
        pretty_type:
          type: string
          description: Human-readable file type.
          example: example_value
        user:
          type: string
          description: User ID of the user who uploaded the file.
          example: example_value
        user_team:
          type: string
          description: Team ID of the user who uploaded the file.
          example: example_value
        editable:
          type: boolean
          description: Whether the file content is editable.
          example: true
        size:
          type: integer
          description: File size in bytes.
          example: 10
        mode:
          type: string
          description: File mode (e.g., "hosted", "external", "snippet", "post").
          example: example_value
        is_external:
          type: boolean
          description: Whether the file is externally hosted.
          example: true
        external_type:
          type: string
          description: Type of external file.
          example: example_value
        is_public:
          type: boolean
          description: Whether the file is public.
          example: true
        public_url_shared:
          type: boolean
          example: https://www.example.com
        display_as_bot:
          type: boolean
          example: true
        username:
          type: string
          example: example_value
        url_private:
          type: string
          format: uri
          description: URL to access the file. Requires authentication.
          example: https://www.example.com
        url_private_download:
          type: string
          format: uri
          description: URL to download the file. Requires authentication.
          example: https://www.example.com
        permalink:
          type: string
          format: uri
          description: Permalink URL for the file.
          example: https://www.example.com
        permalink_public:
          type: string
          format: uri
          description: Public permalink URL for the file (if shared publicly).
          example: https://www.example.com
        channels:
          type: array
          description: Array of channel IDs where the file is shared.
          items:
            type: string
          example: []
        groups:
          type: array
          description: Array of private channel IDs where the file is shared.
          items:
            type: string
          example: []
        ims:
          type: array
          description: Array of DM IDs where the file is shared.
          items:
            type: string
          example: []
        shares:
          type: object
          description: Sharing information broken down by type.
          example: example_value
        comments_count:
          type: integer
          description: Number of comments on the file.
          example: 10
    Message:
      type: object
      description: A Slack message object representing a single message in a conversation. Messages can contain text, blocks, attachments, files, and reactions.
      properties:
        type:
          type: string
          description: Always "message" for messages.
          const: message
          example: example_value
        subtype:
          type: string
          description: Optional subtype indicating a specialized message type such as bot_message, channel_join, channel_leave, etc.
          example: example_value
        channel:
          type: string
          description: The channel ID where the message was posted.
          example: example_value
        user:
          type: string
          description: The user ID of the message author.
          example: example_value
        text:
          type: string
          description: The text content of the message.
          example: example_value
        ts:
          type: string
          description: Unique timestamp identifier for the message, also serves as the message ID. Format is Unix epoch with microseconds (e.g., "1503435956.000247").
          example: example_value
        thread_ts:
          type: string
          description: The timestamp of the parent message in a thread. Present only for threaded replies.
          example: example_value
        reply_count:
          type: integer
          description: Number of replies in the thread.
          example: 10
        reply_users_count:
          type: integer
          description: Number of unique users who have replied in the thread.
          example: 10
        latest_reply:
          type: string
          description: Timestamp of the most recent reply in the thread.
          example: example_value
        reply_users:
          type: array
          description: Array of user IDs who have replied in the thread.
          items:
            type: string
          example: []
        blocks:
          type: array
          description: An array of Block Kit layout blocks used for rich message formatting.
          items:
            type: object
          example: []
        attachments:
          type: array
          description: An array of message attachments.
          items:
            type: object
            properties:
              id:
                type: integer
              color:
                type: string
              fallback:
                type: string
              text:
                type: string
              pretext:
                type: string
              author_name:
                type: string
              author_link:
                type: string
                format: uri
              author_icon:
                type: string
                format: uri
              title:
                type: string
              title_link:
                type: string
                format: uri
              fields:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    value:
                      type: string
                    short:
                      type: boolean
              footer:
                type: string
              footer_icon:
                type: string
                format: uri
              ts:
                type: integer
          example: []
        files:
          type: array
          description: An array of file objects attached to the message.
          items:
            $ref: '#/components/schemas/File'
          example: []
        reactions:
          type: array
          description: An array of emoji reactions on this message.
          items:
            type: object
            properties:
              name:
                type: string
                description: Emoji name without colons.
              count:
                type: integer
                description: Number of users who added this reaction.
              users:
                type: array
                description: User IDs of users who added this reaction.
                items:
                  type: string
          example: []
        edited:
          type: object
          description: Edit information if the message was edited.
          properties:
            user:
              type: string
            ts:
              type: string
          example: example_value
        bot_id:
          type: string
          description: Bot ID if the message was posted by a bot.
          example: '500123'
        bot_profile:
          type: object
          description: Bot profile information if posted by a bot.
          properties:
            id:
              type: string
            deleted:
              type: boolean
            name:
              type: string
            updated:
              type: integer
            app_id:
              type: string
            icons:
              type: object
          example: example_value
        metadata:
          type: object
          description: Custom metadata attached to the message by an application.
          properties:
            event_type:
              type: string
            event_payload:
              type: object
          example: example_value
        permalink:
          type: string
          format: uri
          description: Permalink URL for the message.
          example: https://www.example.com
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Slack API uses Bearer token authentication. Pass a bot token or user token in the Authorization header.