Slack Lists API

openapi: 3.2.0
info:
  title: Slack Lists API
  description: The Slack Lists API provides methods for programmatically creating and managing Lists, a structured data surface in Slack for tracking work items, tasks, and records. Methods include slackLists.create and slackLists.update for managing lists, slackLists.items.create, slackLists.items.update, slackLists.items.delete, and slackLists.items.deleteMultiple for managing individual records, slackLists.items.list and slackLists.items.info for retrieving records, and slackLists.download.start for exporting list data.
  version: 1.0.0
  contact:
    name: Slack Developer Relations
    url: https://docs.slack.dev
servers:
- url: https://slack.com/api
tags:
- name: Lists
paths:
  /slackLists.create:
    post:
      tags:
      - Lists
      summary: Create List
      description: Creates a new Slack List for tracking work items, tasks, or records.
      operationId: postSlackListsCreate
      parameters:
      - name: token
        in: header
        description: 'Authentication token. Requires scope: `lists:write`'
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - title
              - channel_id
              type: object
              properties:
                title:
                  type: string
                  description: Title of the list.
                channel_id:
                  type: string
                  description: Channel to create the list in.
                columns:
                  type: array
                  description: Column definitions for the list.
                  items:
                    type: object
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  list:
                    type: object
              example:
                ok: true
        default:
          description: Error response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  error:
                    type: string
              example:
                ok: false
                error: invalid_auth
      security:
      - slackAuth:
        - lists:write
  /slackLists.update:
    post:
      tags:
      - Lists
      summary: Update List
      description: Updates an existing Slack List's title or column configuration.
      operationId: postSlackListsUpdate
      parameters:
      - name: token
        in: header
        description: 'Authentication token. Requires scope: `lists:write`'
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - list_id
              type: object
              properties:
                list_id:
                  type: string
                  description: ID of the list to update.
                title:
                  type: string
                  description: New title of the list.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
              example:
                ok: true
        default:
          description: Error response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  error:
                    type: string
              example:
                ok: false
                error: list_not_found
      security:
      - slackAuth:
        - lists:write
  /slackLists.items.create:
    post:
      tags:
      - Lists
      summary: Create List Item
      description: Creates a new item (row) in a Slack List.
      operationId: postSlackListsItemsCreate
      parameters:
      - name: token
        in: header
        description: 'Authentication token. Requires scope: `lists:write`'
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - list_id
              - column_values
              type: object
              properties:
                list_id:
                  type: string
                  description: ID of the list to add the item to.
                column_values:
                  type: object
                  description: Map of column IDs to their values for the new item.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  item:
                    type: object
              example:
                ok: true
        default:
          description: Error response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  error:
                    type: string
              example:
                ok: false
                error: list_not_found
      security:
      - slackAuth:
        - lists:write
  /slackLists.items.update:
    post:
      tags:
      - Lists
      summary: Update List Item
      description: Updates an existing item (row) in a Slack List.
      operationId: postSlackListsItemsUpdate
      parameters:
      - name: token
        in: header
        description: 'Authentication token. Requires scope: `lists:write`'
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - list_id
              - item_id
              - column_values
              type: object
              properties:
                list_id:
                  type: string
                  description: ID of the list.
                item_id:
                  type: string
                  description: ID of the item to update.
                column_values:
                  type: object
                  description: Map of column IDs to their new values.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
              example:
                ok: true
        default:
          description: Error response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  error:
                    type: string
              example:
                ok: false
                error: item_not_found
      security:
      - slackAuth:
        - lists:write
  /slackLists.items.delete:
    post:
      tags:
      - Lists
      summary: Delete List Item
      description: Deletes a single item (row) from a Slack List.
      operationId: postSlackListsItemsDelete
      parameters:
      - name: token
        in: header
        description: 'Authentication token. Requires scope: `lists:write`'
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
              - list_id
              - item_id
              type: object
              properties:
                list_id:
                  type: string
                  description: ID of the list.
                item_id:
                  type: string
                  description: ID of the item to delete.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
              example:
                ok: true
        default:
          description: Error response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  error:
                    type: string
              example:
                ok: false
                error: item_not_found
      security:
      - slackAuth:
        - lists:write
  /slackLists.items.list:
    get:
      tags:
      - Lists
      summary: List Items
      description: Lists all items in a Slack List with optional filtering and pagination.
      operationId: getSlackListsItemsList
      parameters:
      - name: token
        in: query
        description: 'Authentication token. Requires scope: `lists:read`'
        required: true
        schema:
          type: string
      - name: list_id
        in: query
        description: ID of the list to retrieve items from.
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        description: Pagination cursor for retrieving additional pages.
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of items to return.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  items:
                    type: array
                    items:
                      type: object
                  response_metadata:
                    type: object
              example:
                ok: true
                items: []
        default:
          description: Error response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  error:
                    type: string
              example:
                ok: false
                error: list_not_found
      security:
      - slackAuth:
        - lists:read
components:
  securitySchemes:
    slackAuth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://slack.com/oauth/v2/authorize
          tokenUrl: https://slack.com/api/oauth.v2.access
          scopes:
            lists:read: Read lists data
            lists:write: Write lists data