gnt.ai Slack API

openapi: 3.2.0
info:
  title: AI GNT Slack API
  version: 0.1.0
servers:
- url: https://api.gntai.dev
  description: Production
tags:
- name: Slack
paths:
  /v1/slack/install-url:
    get:
      tags:
      - Slack
      summary: Install Url
      operationId: install_url_v1_slack_install_url_get
      security:
      - HTTPBearer: []
      parameters:
      - name: origin
        in: query
        required: false
        schema:
          type: string
          default: web
          title: Origin
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/slack/oauth/callback:
    get:
      tags:
      - Slack
      summary: Oauth Callback
      operationId: oauth_callback_v1_slack_oauth_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: State
      - name: error
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/slack/command:
    post:
      tags:
      - Slack
      summary: Slash Command
      description: '`/brain ` — retargeted at proposing rules,

        replacing the retired knowledge-unit capture pipeline (triage/extract/

        embed) it used to feed. `text` is freeform;

        see _split_command_text above for how it becomes a title/body pair.

        The rest goes through create_draft_rule, the exact same function

        POST /v1/rules and routers/webhooks.py''s ingest_webhook already share

        — same sanitize/tenant-scoping/draft-ceiling behavior as every other

        draft-rule front door, just reached through a slash command instead.


        Bare `/brain`, `/brain help`, and `/brain status` are the three

        read-only, zero-write exits from this handler — matched against the

        whole trimmed `text` up front, before anything below touches

        create_draft_rule. No new Slack app manifest entry: this reuses the

        same `/brain` command and slash-command endpoint rather than

        registering a second one, since `/brain` had no subcommand-style

        parsing to preserve compatibility with. `status` exists so a human

        (or someone verifying the integration works at all) has a way to

        check "is this workspace actually linked to an org" without

        polluting real data by ingesting a throwaway policy just to find out.


        apply_privacy_gate=True below is not optional: a

        Slack message is exactly the ambient third-party content the gate

        exists for — someone''s words in a channel, not a human deliberately

        typing straight into gnt — see gnt.pipeline.privacy_gate''s module

        docstring and create_draft_rule''s own docstring for the full

        reasoning, including the masking-is-permanent tradeoff.


        No Slack-specific rate limit added on top of the shared

        max_draft_rules_per_org ceiling create_draft_rule already enforces.

        Deliberate, not an oversight: routers/webhooks.py''s per-IP/per-org

        limits exist because a webhook ingest token is a leakable bearer

        credential (anyone who obtains the URL can call it indefinitely, with

        nothing else identifying them), and its per-IP limit specifically

        protects the token-lookup DB hit against a flood of requests carrying

        invalid tokens. Neither threat model applies here: this endpoint is

        only ever reachable through Slack''s own signed request (verified

        below, before any DB work runs), the caller-identifying signal is

        Slack''s servers relaying a real signed request rather than any one

        IP, and firing this command still requires being a real member of a

        workspace that installed the app, typing it into Slack''s own UI — a

        materially higher-friction, more accountable path than POSTing a

        bare URL. The shared draft-rule ceiling is the real backstop for a

        compromised or malicious workspace member spamming `/brain`, same as

        it already is for every other draft-rule front door.'
      operationId: slash_command_v1_slack_command_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer