Clarity Slack API

openapi: 3.2.0
info:
  title: Fast Slack API
  version: 0.1.0
tags:
- name: Slack
paths:
  /api/v1/slack/connect:
    get:
      tags:
      - Slack
      summary: Slack Connect
      operationId: slack_connect_api_v1_slack_connect_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/v1/slack/skip:
    post:
      tags:
      - Slack
      summary: Slack Skip
      operationId: slack_skip_api_v1_slack_skip_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/v1/slack/disconnect:
    get:
      tags:
      - Slack
      summary: Slack Disconnect
      operationId: slack_disconnect_api_v1_slack_disconnect_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/v1/slack/signin:
    get:
      tags:
      - Slack
      summary: Slack Signin
      operationId: slack_signin_api_v1_slack_signin_get
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: true
        schema:
          type: string
          title: State
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/slack/get-token:
    get:
      tags:
      - Slack
      summary: Get Slack Token
      operationId: get_slack_token_api_v1_slack_get_token_get
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          title: Team Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/slack/is-onboarded:
    get:
      tags:
      - Slack
      summary: Slack Team Is Onboarded
      operationId: slack_team_is_onboarded_api_v1_slack_is_onboarded_get
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          title: Team Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/slack/search:
    post:
      tags:
      - Slack
      summary: Slack Search Request
      operationId: slack_search_request_api_v1_slack_search_post
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          title: Team Id
      - name: x-request-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Request-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackSearchQuery'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/slack/sources:
    get:
      tags:
      - Slack
      summary: List Sources
      operationId: list_sources_api_v1_slack_sources_get
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          title: Team Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/slack/channels:
    post:
      tags:
      - Slack
      summary: Add Slack Channels
      operationId: add_slack_channels_api_v1_slack_channels_post
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          title: Team Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SlackChannel'
              title: Channels
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Slack
      summary: List Slack Channels
      operationId: list_slack_channels_api_v1_slack_channels_get
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          title: Team Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/slack/all-channels:
    get:
      tags:
      - Slack
      summary: List All Slack Channels
      operationId: list_all_slack_channels_api_v1_slack_all_channels_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/v1/slack/channel/{channel_id}:
    get:
      tags:
      - Slack
      summary: Get Slack Channel
      description: 'Fetch a single Slack channel by ID. Used as a fallback when the

        full channel list fails to load (e.g. large workspaces rate-limited).'
      operationId: get_slack_channel_api_v1_slack_channel__channel_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: channel_id
        in: path
        required: true
        schema:
          type: string
          title: Channel Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackChannelResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/slack/message:
    post:
      tags:
      - Slack
      summary: Send Slack Message
      operationId: send_slack_message_api_v1_slack_message_post
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          title: Team Id
      - name: channel_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel Id
      - name: send_dm
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          default: true
          title: Send Dm
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackMessage'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/slack/set-triage-status:
    post:
      tags:
      - Slack
      summary: Set Triage Status
      description: 'Write a human triage status onto a ticket (called by anecdote-slackbot when a

        triage button on an alert is clicked).


        Direct ES partial write by ``unique_id`` — mirrors agent_qa''s ``set_alert_status``.

        Deliberately NOT the inject pipeline: nothing is recomputed, ``raw_ticket`` /

        ``injection_time`` stay untouched, and no alert webhook can re-fire. The columns

        land as plain filterable fields (absent = untriaged, query via ``exists``).'
      operationId: set_triage_status_api_v1_slack_set_triage_status_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetTriageStatusRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/slack/set-alert-mark:
    post:
      tags:
      - Slack
      summary: Set Alert Mark
      description: 'Write a human alert mark onto a ticket (anecdote-slackbot alert buttons, Social ops).


        Three independent mark groups on one alert: a TOPIC (what the tweet is about),

        an ACTION (what we did about it), and NEW_MODEL (a standalone "about a new

        model" flag). Each request sets one or more; a request carrying only `topic`

        never touches the other fields, so re-marking one group preserves the others.

        Within a group the latest click wins.


        ``mode`` says how the carried groups are applied: ``toggle`` (default, the Slack

        buttons — a re-click undoes), ``set`` (ensure present) or ``unset`` (ensure absent);

        the last two are idempotent for callers that act on many tickets at once.


        The ``Handled`` action additionally stamps ``Alert Handled At`` (+ ``Alert Handled

        By__filter`` when ``by`` is given) the moment it goes ON, keeps that stamp on a repeated

        ``set``, and removes both when it comes OFF — the success-rate arithmetic reads them.


        Same direct-ES contour as set_triage_status above: partial update_by_query

        by ``unique_id``, nothing recomputed, no webhook re-fire, absent field =

        unmarked (query via ``exists``).'
      operationId: set_alert_mark_api_v1_slack_set_alert_mark_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetAlertMarkRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/slack/alert-message:
    post:
      tags:
      - Slack
      summary: Send Alert Message
      description: 'Post one needs-response alert, collapsing repeat authors into threads.


        An author''s first alert lands in the channel and its ``ts`` is remembered on the

        channel''s anchor record (``x-thread-anchors``); every later alert with the same key

        posts into that thread. The record is cleared at shift close, so threading windows run

        close-to-close — alerts thread even before an agent''s first touch opens the next

        shift. No/empty ``thread_key`` (flow templates render a null as "") → plain channel

        post. Kept separate from the generic /message on purpose: alerts need the posted ts +

        channel state, weekly-updates et al. need neither.'
      operationId: send_alert_message_api_v1_slack_alert_message_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertMessageRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/slack/on-alert:
    post:
      tags:
      - Slack
      summary: On Alert
      description: 'Stamp an alert; bind it to the shift only if an agent has one open. Called by the

        alert flow for every alert: stamps ``Alerted`` + ``Alert At`` + ``Alert Channel``

        always, and ``Shift Id`` only when the channel has an open shift. With nobody on shift

        the alert stays UNBOUND backlog — the agent''s Start shift button (open-shift) opens the

        shift and adopts everything with ``Alert At`` since the previous close. Alerts never

        open shifts (that produced phantom 3am shifts whose 13h auto-close fired before the

        agent sat down). Same direct-ES contour as the mark endpoints — no recompute, no

        re-fire.'
      operationId: on_alert_api_v1_slack_on_alert_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnAlertRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/slack/close-shift:
    post:
      tags:
      - Slack
      summary: Close Shift
      description: 'Close the channel''s open shift, assemble + freeze the report, and RETURN its blocks for

        the slackbot to post. 404 (no open shift) is the stale-button / already-closed case.'
      operationId: close_shift_api_v1_slack_close_shift_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloseShiftRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/slack/open-shift:
    post:
      tags:
      - Slack
      summary: Open Shift
      description: 'Start the channel''s shift: the Damage control desk''s "Start shift" button (client ask

        2026-10-15 — a separate button instead of the first mark). Idempotent: when a shift is

        already open it is returned untouched (``opened`` false). A fresh open adopts the unbound

        backlog — alerts that came in since the previous close, capped at 48h — exactly as the

        first touch used to, so the shift''s report covers the pile the agent sat down to.'
      operationId: open_shift_api_v1_slack_open_shift_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenShiftRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/slack/sweep-shifts:
    post:
      tags:
      - Slack
      summary: Sweep Shifts
      description: 'Cron entrypoint (the auto-close workflow calls this ~every 30 min): auto-close every open

        shift older than 13h, freeze each report, and return the blocks per channel for the flow to

        post.'
      operationId: sweep_shifts_api_v1_slack_sweep_shifts_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SweepShiftsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    SlackSearchQuery:
      properties:
        query:
          type: string
          title: Query
        user:
          anyOf:
          - type: string
          - type: 'null'
          title: User
        main_field:
          anyOf:
          - type: string
          - type: 'null'
          title: Main Field
          default: message_text
        filters:
          items: {}
          type: array
          title: Filters
          default: []
        additional_fields:
          items:
            type: string
          type: array
          title: Additional Fields
          default: []
        custom_prompt_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Custom Prompt End
      type: object
      required:
      - query
      title: SlackSearchQuery
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    OnAlertRequest:
      properties:
        project_id:
          type: integer
          title: Project Id
        unique_id:
          type: string
          title: Unique Id
        channel_id:
          type: string
          title: Channel Id
      type: object
      required:
      - project_id
      - unique_id
      - channel_id
      title: OnAlertRequest
    AlertMessageRequest:
      properties:
        project_id:
          type: integer
          title: Project Id
        channel_id:
          type: string
          title: Channel Id
        team_id:
          type: string
          title: Team Id
        unique_id:
          type: string
          title: Unique Id
        blocks:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Blocks
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
        thread_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Thread Key
      type: object
      required:
      - project_id
      - channel_id
      - team_id
      - unique_id
      - blocks
      title: AlertMessageRequest
    CloseShiftRequest:
      properties:
        project_id:
          type: integer
          title: Project Id
        channel_id:
          type: string
          title: Channel Id
        by:
          anyOf:
          - type: string
          - type: 'null'
          title: By
        auto:
          type: boolean
          title: Auto
          default: false
      type: object
      required:
      - project_id
      - channel_id
      title: CloseShiftRequest
    OpenShiftRequest:
      properties:
        project_id:
          type: integer
          title: Project Id
        channel_id:
          type: string
          title: Channel Id
        by:
          anyOf:
          - type: string
          - type: 'null'
          title: By
      type: object
      required:
      - project_id
      - channel_id
      title: OpenShiftRequest
    SetTriageStatusRequest:
      properties:
        project_id:
          type: integer
          title: Project Id
        unique_id:
          type: string
          title: Unique Id
        status:
          type: string
          title: Status
        by:
          anyOf:
          - type: string
          - type: 'null'
          title: By
      type: object
      required:
      - project_id
      - unique_id
      - status
      title: SetTriageStatusRequest
    SweepShiftsRequest:
      properties:
        project_id:
          type: integer
          title: Project Id
      type: object
      required:
      - project_id
      title: SweepShiftsRequest
    SlackChannel:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        type:
          type: string
          title: Type
      type: object
      required:
      - id
      - name
      - type
      title: SlackChannel
    SetAlertMarkRequest:
      properties:
        project_id:
          type: integer
          title: Project Id
        unique_id:
          type: string
          title: Unique Id
        topic:
          anyOf:
          - type: string
          - type: 'null'
          title: Topic
        action:
          anyOf:
          - type: string
          - type: 'null'
          title: Action
        new_model:
          anyOf:
          - type: string
          - type: 'null'
          title: New Model
        by:
          anyOf:
          - type: string
          - type: 'null'
          title: By
        channel_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel Id
        open_shift:
          type: boolean
          title: Open Shift
          default: false
        mode:
          type: string
          enum:
          - toggle
          - set
          - unset
          title: Mode
          default: toggle
      type: object
      required:
      - project_id
      - unique_id
      title: SetAlertMarkRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SlackMessage:
      properties:
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
        blocks:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Blocks
      type: object
      title: SlackMessage
    SlackChannelResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
      type: object
      required:
      - id
      - name
      title: SlackChannelResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic