Archastro Slack Channel Bindings API

openapi: 3.0.0
info:
  description: Agent-first API for runtime + developer control-plane operations (users, teams, agents, routines, context, workflows, integrations, and webhooks).
  title: ArchAstro Platform Activity Feed Slack Channel Bindings API
  version: v1
tags:
- name: Slack Channel Bindings
paths:
  /api/v1/slack_channel_bindings:
    get:
      description: 'Returns a page of Slack channel bindings visible to the authenticated user.

        Results can be filtered by integration, team, agent, or organization. Omit all

        filter params to retrieve every binding the caller can see.


        Pagination is page-based. Pass `page` and `per_page` to navigate large result

        sets. `page` must be a positive integer; `per_page` must be between 1 and 100.

        Invalid values return 400.'
      operationId: get_api_v1_slack_channel_bindings
      parameters:
      - description: Number of bindings to return per page. Defaults to 25; maximum is 100.
        example: 1
        in: query
        name: per_page
        required: false
        schema:
          type: integer
      - description: Page number to retrieve, 1-indexed. Defaults to 1. Must be a positive integer.
        example: 1
        in: query
        name: page
        required: false
        schema:
          type: integer
      - description: Return only bindings bound to one of these team IDs. Omit to return bindings for all teams.
        example:
        - string
        in: query
        name: team
        required: false
        schema:
          items:
            type: string
          type: array
      - description: Return only bindings that belong to one of these organization IDs. Omit to return bindings across all organizations visible to the caller.
        example:
        - string
        in: query
        name: org
        required: false
        schema:
          items:
            type: string
          type: array
      - description: Return only bindings that have at least one of these agent user IDs attached. Omit to return bindings regardless of agent attachment.
        example:
        - string
        in: query
        name: agent
        required: false
        schema:
          items:
            type: string
          type: array
      - description: Return only bindings whose Slack integration matches one of these integration IDs. Omit to return bindings across all integrations.
        example:
        - string
        in: query
        name: integration
        required: false
        schema:
          items:
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackChannelBindingListResponse'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      summary: List Slack channel bindings
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Slack Channel Bindings
    post:
      description: 'Creates a new binding between a Slack channel and a team, or updates the

        existing binding if one already exists for the given channel. The caller also

        supplies a list of agents to attach to the binding and enroll as members of the

        destination team.


        The caller must have team-manage rights on the destination team (and on the

        currently bound team if the channel is being re-pointed). Returns 403 if

        permission is insufficient. All write steps are idempotent, so retrying after

        a partial failure is safe.


        On success the REST endpoint returns 201 Created. The script binding

        (`slack.channel_bindings.upsert`) returns the full binding object including the

        attached agents.'
      operationId: post_api_v1_slack_channel_bindings
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              example:
                agent_user_ids:
                - string
                channel_id: string
                customer_label: string
                is_ext_shared_cached: true
                slack_team_id: string
                team_id: string
              properties:
                agent_user_ids:
                  description: List of agent user IDs to attach to the binding and enroll as members of the destination team. Pass an empty array to bind the channel without attaching any agents.
                  example:
                  - string
                  items:
                    type: string
                  type: array
                channel_id:
                  description: Slack channel ID to bind (e.g. `C01234ABCDE`). Acts as the natural key of the binding within the workspace.
                  example: string
                  type: string
                customer_label:
                  description: Human-readable label for the customer associated with this channel. Stored in the binding's config. `null` if omitted.
                  example: string
                  type: string
                is_ext_shared_cached:
                  description: Cached value of Slack's `is_ext_shared` flag for the channel. When provided, this value is persisted on the binding to avoid repeated Slack API lookups. `null` if omitted.
                  example: true
                  type: boolean
                slack_team_id:
                  description: Slack workspace team ID that the channel belongs to (e.g. `T01234ABCDE`). Identifies which Slack integration to use.
                  example: string
                  type: string
                team_id:
                  description: ID of the team to bind the Slack channel to. The caller must have team-manage rights on this team.
                  example: string
                  type: string
              required:
              - agent_user_ids
              - channel_id
              - slack_team_id
              - team_id
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackChannelBinding'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden; The Slack integration referenced by this binding is not visible to the caller
        '404':
          description: Agent not found; Team not found
        '422':
          description: Invalid parameters; Binding org_id does not match the integration's org_id
      summary: Create or update a Slack channel binding
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Slack Channel Bindings
  /api/v1/slack_channel_bindings/{channel}:
    delete:
      description: 'Removes the binding between a Slack channel and its associated team. The

        channel is identified by its Slack channel ID together with the `slack_team_id`

        that scopes it to a specific Slack workspace. Removing the binding does not

        delete the bound team or any conversation threads scoped to it; decommission

        those resources separately if required.


        The caller must have team-manage rights on the team the channel is currently

        bound to. Returning 403 indicates insufficient permission; returning 404

        indicates the binding does not exist or is not visible to the caller.


        The REST endpoint returns 204 No Content on success. The script binding

        (`slack.channel_bindings.delete`) returns a confirmation object so script

        callers can verify success without an additional fetch. Both paths are

        idempotent — retrying after a partial failure is safe.'
      operationId: delete_api_v1_slack_channel_bindings__channel
      parameters:
      - description: Slack channel ID of the binding to delete (e.g. `C01234ABCDE`).
        example: string
        in: path
        name: channel
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Deletion confirmation returned by the script binding. The REST endpoint returns 204 No Content with no body.
                example:
                  channel: string
                  deleted: true
                properties:
                  channel:
                    description: Slack channel ID of the binding that was deleted.
                    example: string
                    type: string
                  deleted:
                    description: Always `true` when the binding was successfully removed.
                    example: true
                    type: boolean
                required:
                - channel
                - deleted
                type: object
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden; The Slack integration referenced by this binding is not visible to the caller
        '404':
          description: Slack channel binding not found
        '422':
          description: Invalid parameters
      summary: Delete a Slack channel binding
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Slack Channel Bindings
    get:
      description: 'Returns the Slack channel binding identified by a Slack channel ID and workspace

        team ID pair. Use this endpoint to look up the team and agents currently bound

        to a specific Slack channel.


        The `channel` path parameter is the Slack channel ID; `slack_team_id` identifies

        the Slack workspace the channel belongs to, disambiguating channels with the same

        ID across workspaces. Both parameters are required. Returns 404 if no binding

        exists for the given pair or the associated Slack integration is not visible to

        the caller.'
      operationId: get_api_v1_slack_channel_bindings__channel
      parameters:
      - description: Slack channel ID of the binding to retrieve (e.g. `C01234ABCDE`).
        example: string
        in: path
        name: channel
        required: true
        schema:
          type: string
      - description: Slack workspace team ID that the channel belongs to (e.g. `T01234ABCDE`). Used together with `channel` to uniquely identify the binding.
        example: string
        in: query
        name: slack_team_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackChannelBinding'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: The Slack integration referenced by this binding is not visible to the caller
        '404':
          description: Slack channel binding not found
        '422':
          description: Invalid parameters
      summary: Retrieve a Slack channel binding
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Slack Channel Bindings
components:
  schemas:
    SlackChannelBinding:
      description: A binding that connects a Slack channel to an ArchAstro team and one or more agents, enabling those agents to receive and respond to messages in that channel.
      example:
        agents:
        - string
        channel: C01234ABCDE
        customer_label: string
        id: string
        integration: string
        is_ext_shared_cached: true
        team: string
      properties:
        agents:
          description: IDs of the agents attached to this binding. Empty array when no agents are assigned.
          example:
          - string
          items:
            type: string
          type: array
        channel:
          description: Slack channel ID (e.g. `C01234ABCDE`) that this binding targets.
          example: C01234ABCDE
          type: string
        customer_label:
          description: Human-readable label identifying the customer, derived from the binding's embedded config. `null` when not set.
          example: string
          type: string
        id:
          description: Unique identifier for this Slack channel binding.
          example: string
          type: string
        integration:
          description: ID of the Slack integration that owns this binding.
          example: string
          type: string
        is_ext_shared_cached:
          description: Cached value of Slack's `is_ext_shared` flag for this channel. May be stale relative to Slack's current state.
          example: true
          type: boolean
        team:
          description: ID of the ArchAstro team this channel is bound to.
          example: string
          type: string
      required:
      - id
      type: object
    SlackChannelBindingListResponse:
      description: Paginated list of Slack channel bindings for the requested integration or team. Use the `page` and `per_page` fields to navigate pages of results.
      example:
        data:
        - agents:
          - string
          channel: C01234ABCDE
          customer_label: string
          id: string
          integration: string
          is_ext_shared_cached: true
          team: string
        page: 1
        per_page: 20
        total_count: 1
        total_pages: 1
      properties:
        data:
          description: Array of Slack channel binding objects for the current page.
          items:
            $ref: '#/components/schemas/SlackChannelBinding'
          type: array
        page:
          description: Current page number (1-indexed).
          example: 1
          type: integer
        per_page:
          description: Maximum number of bindings returned per page.
          example: 20
          type: integer
        total_count:
          description: Total number of Slack channel bindings matching the query across all pages.
          example: 1
          type: integer
        total_pages:
          description: Total number of pages available at the current `per_page` size.
          example: 1
          type: integer
      required:
      - data
      - page
      - per_page
      - total_count
      - total_pages
      type: object
x-archastro-docs-scope: external
x-auth-schemes:
  bearer:
    description: User JWT in Authorization header
    scheme: bearer
    type: http
  device_flow:
    description: Third-party device flow token — requires per-action opt-in
    scheme: bearer
    type: http
    x-token-use: third_party
  publishable_key:
    description: Publishable API key — identifies the app
    in: header
    name: x-archastro-api-key
    prefix: pk_
    type: api_key
  secret_key:
    description: Secret API key — full admin access, no user JWT required
    in: header
    name: x-archastro-api-key
    prefix: sk_
    type: api_key
x-channel-auth:
- bearer
x-channels:
- description: 'Channel for real-time chat messaging.


    Supports team-scoped and user-scoped threads with keyed, transient, and direct

    thread access patterns.'
  joins:
  - description: Join a team-scoped thread by ID
    name: join_team_thread
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        limit: 1
        team_id: string
        thread_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        limit:
          example: 1
          type: integer
        team_id:
          example: string
          type: string
        thread_id:
          example: string
          type: string
      required:
      - team_id
      - thread_id
      type: object
    pattern: api:chat:team:{team_id}:thread:{thread_id}
    returns:
      type: object
  - description: Join a team-scoped transient (ephemeral) thread
    name: join_team_transient
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
        team_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
        team_id:
          example: string
          type: string
      required:
      - key
      - team_id
      type: object
    pattern: api:chat:team:{team_id}:transient:{key}
    returns:
      type: object
  - description: Join a user-scoped thread by ID
    name: join_user_thread
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        limit: 1
        thread_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        limit:
          example: 1
          type: integer
        thread_id:
          example: string
          type: string
      required:
      - thread_id
      type: object
    pattern: api:chat:user:thread:{thread_id}
    returns:
      type: object
  - description: Join a user-scoped transient (ephemeral) thread
    name: join_user_transient
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
      required:
      - key
      type: object
    pattern: api:chat:user:transient:{key}
    returns:
      type: object
  - description: Join or create a team-scoped keyed thread
    name: join_team_keyed
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
        team_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
        team_id:
          example: string
          type: string
      required:
      - key
      - team_id
      type: object
    pattern: api:chat:team:{team_id}:key:{key}
    returns:
      type: object
  - description: Join or create a user-scoped keyed thread
    name: join_user_keyed
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
      required:
      - key
      type: object
    pattern: api:chat:user:key:{key}
    returns:
      type: object
  messages:
  - description: Add an emoji reaction to a message
    event: api:chat:add_reaction
    params:
      example:
        emoji: string
        message_id: string
      properties:
        emoji:
          example: string
          type: string
        message_id:
          example: string
          type: string
      required:
      - emoji
      - message_id
      type: object
    returns:
      description: 'Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`.'
      properties: {}
      type: object
  - description: Delete a message
    event: api:chat:delete_message
    params:
      example:
        message_id: string
      properties:
        message_id:
          example: string
          type: string
      required:
      - message_id
      type: object
    returns:
      description: 'Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`.'
      properties: {}
      type: object
  - description: Edit an existing message's content
    event: api:chat:edit_message
    params:
      example:
        content: string
        message_id: string
      properties:
        content:
          example: string
          type: string
        message_id:
          example: string
          type: string
      required:
      - content
      - message_id
      type: object
    returns:
      description: 'Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`.'
      properties: {}
      type: object
  - description: Fork a sub-thread from an existing message
    event: api:chat:fork_thread
    params:
      example:
        message_id: string
        title: Example Title
      properties:
        message_id:
          example: string
          type: string
        title:
          example: Example Title
          type: string
      required:
      - message_id
      type: object
    returns:
      description: Response returned after forking a chat thread. Contains the new thread, its initial chat-room snapshot, and the owning team when applicable.
      example:
        chat_model:
          after_cursor: string
          agent:
            acl:
              add:
              - actions:
                - read
                - write
                principal: string
                principal_type: user
              grants:
              - actions:
                - read
                - write
                principal: string
                principal_type: user
              remove:
              - principal: string
                principal_type: user
            app: dap_0aBcDeFgHiJkLmNoPqRsTu
            created_at: '2024-01-01T00:00:00Z'
            default_model: claude-3-7-sonnet-latest
            email: user@example.com
            id: agi_0aBcDeFgHiJkLmNoPqRsTu
            identity: You are a helpful assistant that answers questions about ArchAstro products.
            last_applied_template_config: cfg_0aBcDeFgHiJkLmNoPqRsTu
            lookup_key: string
            metadata:
              key: value
            name: Example Name
            org: org_0aBcDeFgHiJkLmNoPqRsTu
            org_name: Example Name
            originator: deploy-pipeline
            phone_number: '+15555550123'
            sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
            source_solution:
              solution:
                category_keys:
                - string
                created_at: '2024-01-01T00:00:00Z'
                description: An example description.
                id: id_0aBcDeFgHiJkLmNoPqRsTu
                kind: Solution
                latest_solution: id_0aBcDeFgHiJkLmNoPqRsTu
                latest_version: 1.0.0
                lookup_key: string
                metadata:
                  key: value
                name: Example Name
                org: org_0aBcDeFgHiJkLmNoPqRsTu
                org_logo:
                  file: fil_0aBcDeFgHiJkLmNoPqRsTu
                  height: 600
                  media: med_0aBcDeFgHiJkLmNoPqRsTu
                  mime_type: application/json
                  refresh_url: https://example.com
                  url: https://example.com
                  width: 800
                org_name: Example Name
                org_slug: example-slug
                owners:
                - string
                readme_url: https://example.com
                solution_id: 01234567-89ab-cdef-0123-456789abcdef
                solution_version: 1.2.0
                tag_keys:
                - string
                template_kind: AgentTemplate
                templates:
                - description: An example description.
                  display_name: Example Name
                  id: id_0aBcDeFgHiJkLmNoPqRsTu
                  kind: AgentTemplate
                  lookup_key: string
                  name: Example Name
                  readme_url: https://example.com
                  virtual_path: string
                updated_at: '2024-01-01T00:00:00Z'
                upgrade_available: true
                virtual_path: string
              template:
                created_at: '2024-01-01T00:00:00Z'
                description: An example description.
                display_name: Example Name
                id: id_0aBcDeFgHiJkLmNoPqRsTu
                kind: agent_tool_template
                lookup_key: string
                name: Example Name
                updated_at: '2024-01-01T00:00:00Z'
                virtual_path: string
            team: tem_0aBcDeFgHiJkLmNoPqRsTu
            updated_at: '2024-01-01T00:00:00Z'
            user: usr_0aBcDeFgHiJkLmNoPqRsTu
          before_cursor: string
          is_transient: true
          members:
          - agent:
              acl:
                add:
                - actions:
                  - read
                  - write
                  principal: string
                  principal_type: user
                grants:
                - actions:
                  - read
                  - write
                  principal: string
                  principal_type: user
                remove:
                - principal: string
                  principal_type: user
              app: dap_0aBcDeFgHiJkLmNoPqRsTu
              created_at: '2024-01-01T00:00:00Z'
              default_model: claude-3-7-sonnet-latest
              email: user@example.com
              id: agi_0aBcDeFgHiJkLmNoPqRsTu
              identity: You are a helpful assistant that answers questions about ArchAstro products.
              last_applied_template_config: cfg_0aBcDeFgHiJkLmNoPqRsTu
              lookup_key: string
              metadata:
                key: value
              name: Example Name
              org: org_0aBcDeFgHiJkLmNoPqRsTu
              org_name: Example Name
              originator: deploy-pipeline
              phone_number: '+15555550123'
              sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
              source_solution:
                solution:
                  category_keys:
                  - string
                  created_at: '2024-01-01T00:00:00Z'
                  description: An example description.
                  id: id_0aBcDeFgHiJkLmNoPqRsTu
                  kind: Solution
                  latest_solution: id_0aBcDeFgHiJkLmNoPqRsTu
                  latest_version: 1.0.0
                  lookup_key: string
                  metadata:
                    key: value
                  name: Example Name
                  org: org_0aBcDeFgHiJkLmNoPqRsTu
                  org_logo:
                    file: fil_0aBcDeFgHiJkLmNoPqRsTu
                    height: 600
                    media: med_0aBcDeFgHiJkLmNoPqRsTu
                    mime_type: application/json
                    refresh_url: https://example.com
                    url: https://example.com
                    width: 800
                  org_name: Example Name
                  org_slug: example-slug
                  owners:
                  - string
                  readme_url: https://example.com
                  solution_id: 01234567-89ab-cdef-0123-456789abcdef
                  solution_version: 1.2.0
                  tag_keys:
                  - string
                  template_kind: AgentTemplate
                  templates:
                  - description: An example description.
                    display_name: Example Name
                    id: id_0aBcDeFgHiJkLmNoPqRsTu
                    kind: AgentTemplate
                    lookup_key: string
                    name: Example Name
                    readme_url: https://example.com
                    virtual_path: string
                  updated_at: '2024-01-01T00:00:00Z'
                  upgrade_available: true
                  virtual_path: string
                template:
                  created_at: '2024-01-01T00:00:00Z'
                  description: An example description.
                  display_name: Example Name
                  id: id_0aBcDeFgHiJkLmNoPqRsTu
                  kind: agent_tool_template
                  lookup_key: string
                  name: Example Name
                  updated_at: '2024-01-01T00:00:00Z'
                  virtual_path: string
              team: tem_0aBcDeFgHiJkLmNoPqRsTu
              updated_at: '2024-01-01T00:00:00Z'
              user: usr_0aBcDeFgHiJkLmNoPqRsTu
            membership_type: owner
            type: user
            user:
              alias: jdoe
              app: dap_0aBcDeFgHiJkLmNoPqRsTu
              app_name: Example Name
              email: user@example.com
              id: usr_0aBcDeFgHiJkLmNoPqRsTu
              is_system_user: true
              metadata:
                key: value
              name: Example Name
              org: org_0aBcDeFgHiJkLmNoPqRsTu
              org_name: Example Name
              org_role: member
              sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
              sandbox_name: Example Name
          messages:
          - actors:
            - alias: alice
              id: user-usr_01j3k5m7n9p2r4s6t8v0w1x2
              name: Example Name
              profile_picture:
                file: fil_0aBcDeFgHiJkLmNoPqRsTu
                height: 600
                media: med_0aBcDeFgHiJkLmNoPqRsTu
                mime_type: application/json
                refresh_url: https://example.com
                url: https://example.com
                width: 800
            agent: agi_0aBcDeFgHiJkLmNoPqRsTu
            attachments:
            - content_type: application/json
              description: An example description.
              filename: string
              height: 1
              id: string
              image_height: 1
              image_source:
                file: fil_0aBcDeFgHiJkLmNoPqRsTu
                height: 600
                media: med_0aBcDeFgHiJkLmNoPqRsTu
                mime_type: application/json
                refresh_url: https://example.com
                url: https://example.com
                width: 800
              image_url: https://example.com
              image_width: 1
              media_type: application/json
              name: Example Name
              object: {}
              title: Example Title
              type: file
              url: https://example.com
              variants:
              - content_type: application/json
                created_at: '2024-01-01T00:00:00Z'
                file: fil_0aBcDeFgHiJkLmNoPqRsTu
                filename: string
                height: 600
                id: mvr_0aBcDeFgHiJkLmNoPqRsTu
                image_source:
                  file: fil_0aBcDeFgHiJkLmNoPqRsTu
                  height: 600
                  media: med_0aBcDeFgHiJkLmNoPqRsTu
                  mime_type: application/json
                  refresh_url: https://example.com
                  url: https://example.com
                  width: 800
                updated_at: '2024-01-01T00:00:00Z'
                url: https://example.com
                variant_key: original
                width: 800
              version: 1
              width: 1
            branched_thread: string
            content: Hello, how can I help you today?
            created_at: '2024-01-01T00:00:00Z'
            has_replies: true
            id: msg_0aBcDeFgHiJkLmNoPqRsTu
            idempotency_key: 01234567-89ab-cdef-01

# --- truncated at 32 KB (997 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/archastro/refs/heads/main/openapi/archastro-slack-channel-bindings-api-openapi.yml