Derive Slack API

openapi: 3.2.0
info:
  title: Derive Slack API
  version: 1.0.0
  description: 'Derive''s HTTP API. Every response shape here is the single source of truth for the web client — generated from the same Zod schemas that back this reference, so the docs never drift from the running API.


    **Auth:** a session cookie (browser) or a bearer token (agents and the CLI). Most write routes are scoped to the caller''s active workspace. The `/v1` paths are the stable product surface; `/openapi.json` serves this spec and `/docs` renders it.'
tags:
- name: Slack
  description: Slack connection status and integration toggles.
paths:
  /v1/slack:
    get:
      tags:
      - Slack
      summary: Slack connection status for the signed-in user's workspace
      responses:
        '200':
          description: Whether Slack is available + connected, the team name, and re-auth state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackStatus'
      operationId: getV1Slack
      x-operation-id-source: derived
    delete:
      tags:
      - Slack
      summary: Disconnect Slack from the workspace (Admin only)
      responses:
        '204':
          description: Slack was disconnected.
      operationId: deleteV1Slack
      x-operation-id-source: derived
  /v1/slack/subscriptions:
    get:
      tags:
      - Slack
      summary: List the workspace's Slack channel subscriptions (Admin only)
      responses:
        '200':
          description: The workspace's subscriptions, plus the event types one can carry — the server is the source of that list so the client can't drift from it.
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscriptions:
                    type: array
                    items:
                      $ref: '#/components/schemas/SlackSubscription'
                  event_options:
                    type: array
                    items:
                      type: string
                      enum:
                      - comment.created
                      - version.published
                      - review.requested
                      - review.sent_back
                required:
                - subscriptions
                - event_options
      operationId: getV1SlackSubscriptions
      x-operation-id-source: derived
    post:
      tags:
      - Slack
      summary: Subscribe a channel to workspace activity (Admin only)
      responses:
        '201':
          description: The created (or updated) subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackSubscription'
      operationId: postV1SlackSubscriptions
      x-operation-id-source: derived
  /v1/slack/subscriptions/{id}:
    patch:
      tags:
      - Slack
      summary: Update a channel subscription (Admin only)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The updated subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackSubscription'
      operationId: patchV1SlackSubscriptionsById
      x-operation-id-source: derived
    delete:
      tags:
      - Slack
      summary: Remove a channel subscription (Admin only)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '204':
          description: The subscription was removed.
      operationId: deleteV1SlackSubscriptionsById
      x-operation-id-source: derived
  /v1/slack/channels:
    get:
      tags:
      - Slack
      summary: List public Slack channels for the subscription picker (Admin only)
      responses:
        '200':
          description: Public channels in the connected workspace.
          content:
            application/json:
              schema:
                type: object
                properties:
                  channels:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                      required:
                      - id
                      - name
                required:
                - channels
      operationId: getV1SlackChannels
      x-operation-id-source: derived
components:
  schemas:
    SlackStatus:
      type: object
      properties:
        available:
          type: boolean
          description: True if this instance has Slack configured at all
        connected:
          type: boolean
          description: True if this workspace has connected a Slack team
        team_name:
          type:
          - string
          - 'null'
          description: The connected Slack team's name, or null if not connected
        needs_reauth:
          type: boolean
          description: Whether the stored bot token needs a re-auth — a failed auth/scope call, or Slack reporting the app uninstalled or its token revoked
        slack_dm:
          type: boolean
          description: The caller's "DM me for important updates" preference (agent completions, mentions, review requests, shares)
        review_email:
          type: boolean
          description: The caller's opt-in preference for review-request email (default false)
        linked:
          type: boolean
          description: Whether the caller has linked their Slack identity for the connected team
      required:
      - available
      - connected
      - team_name
      - needs_reauth
      - slack_dm
      - review_email
      - linked
    SlackSubscription:
      type: object
      properties:
        id:
          type: string
        channel_id:
          type: string
          description: Slack channel id, e.g. C0123ABC456
        channel_name:
          type:
          - string
          - 'null'
          description: 'The channel''s #name for display, or null if unknown'
        scope_kind:
          type: string
          enum:
          - workspace
          - collection
          description: Whether this covers the whole workspace or one collection
        scope_id:
          type: string
          description: The collection id when scope_kind is "collection"; empty for a workspace scope
        scope_title:
          type:
          - string
          - 'null'
          description: The scoped collection's title, resolved for display. Null for a workspace scope, and also when the collection has been deleted — the subscription then matches nothing, and saying so is more useful than a bare id.
        events:
          type: string
          description: Comma-separated event types to deliver, or "*" for all events
        authors:
          type: string
          enum:
          - all
          - human
          - agent
          description: 'Whose activity reaches this channel: everyone, only people, or only agents'
        active:
          anyOf:
          - type: number
            enum:
            - 0
          - type: number
            enum:
            - 1
          description: Whether deliveries are enabled (1) or paused (0)
        created_at:
          type: string
      required:
      - id
      - channel_id
      - channel_name
      - scope_kind
      - scope_id
      - scope_title
      - events
      - authors
      - active
      - created_at