Knock Providers API

openapi: 3.2.0
info:
  title: Knock Providers API
  version: '1.0'
  description: A provider represents a third-party service that Knock integrates with and is configured via a channel.
servers:
- url: https://api.knock.app
  variables: {}
security:
- BearerAuth: []
tags:
- description: A provider represents a third-party service that Knock integrates with and is configured via a channel.
  name: Providers
paths:
  /v1/providers/ms-teams/{channel_id}/channels:
    get:
      callbacks: {}
      description: List the Microsoft Teams channels within a team. By default, archived and private channels are excluded from the results.
      operationId: listChannelsForMsTeamsProvider
      parameters:
      - description: The ID of the Knock Microsoft Teams channel to get channels for.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
      - description: A JSON encoded string containing the Microsoft Teams tenant object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: ms_teams_tenant_object
        required: true
        schema:
          type: string
      - description: Microsoft Teams team ID.
        in: query
        name: team_id
        required: true
        schema:
          type: string
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to filter channels.'
        example: displayName eq 'General'
        in: query
        name: query_options.$filter
        required: false
        schema:
          type: string
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to select specific properties.'
        example: id,displayName,description
        in: query
        name: query_options.$select
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelsForMsTeamsProviderResponse'
          description: OK
      summary: List channels
      tags:
      - Providers
      x-ratelimit-tier: 2
  /v1/providers/slack/{channel_id}/revoke_access:
    put:
      callbacks: {}
      description: Revoke access for a Slack channel.
      operationId: slackProviderRevokeAccess
      parameters:
      - description: The ID of the Knock Slack channel to revoke access for.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
      - description: A JSON encoded string containing the access token object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: access_token_object
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A response indicating the operation was successful.
                example:
                  ok: ok
                properties:
                  ok:
                    description: OK response.
                    example: ok
                    type: string
                title: SuccessResponse
                type: object
          description: OK
        '403':
          content:
            application/json:
              schema:
                description: Authentication error response
                example:
                  code: authorization
                  message: Access token not set.
                  status: 403
                  type: authentication_error
                properties:
                  code:
                    description: The error code.
                    example: authorization
                    type: string
                  message:
                    description: The error message.
                    example: Access token not set.
                    type: string
                  status:
                    description: The HTTP status code.
                    example: 403
                    type: integer
                  type:
                    description: The error type.
                    example: authentication_error
                    type: string
                required:
                - code
                - message
                - status
                - type
                title: AuthenticationError
                type: object
          description: Forbidden
      summary: Revoke access
      tags:
      - Providers
      x-ratelimit-tier: 2
  /v1/providers/ms-teams/{channel_id}/auth_check:
    get:
      callbacks: {}
      description: Check if a connection to Microsoft Teams has been authorized for a given Microsoft Teams tenant object.
      operationId: msTeamsProviderAuthCheck
      parameters:
      - description: The ID of the Knock Microsoft Teams channel to check.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
      - description: A JSON encoded string containing the Microsoft Teams tenant object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: ms_teams_tenant_object
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MsTeamsAuthCheckResponse'
          description: OK
      summary: Check auth
      tags:
      - Providers
      x-ratelimit-tier: 2
  /v1/providers/ms-teams/{channel_id}/revoke_access:
    put:
      callbacks: {}
      description: Remove a Microsoft Entra tenant ID from a Microsoft Teams tenant object.
      operationId: msTeamsProviderRevokeAccess
      parameters:
      - description: The ID of the Knock Microsoft Teams channel to revoke access for.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
      - description: A JSON encoded string containing the Microsoft Teams tenant object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: ms_teams_tenant_object
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A response indicating the operation was successful.
                example:
                  ok: ok
                properties:
                  ok:
                    description: OK response.
                    example: ok
                    type: string
                title: SuccessResponse
                type: object
          description: OK
        '403':
          content:
            application/json:
              schema:
                description: Authentication error response
                example:
                  code: authorization
                  message: Access token not set.
                  status: 403
                  type: authentication_error
                properties:
                  code:
                    description: The error code.
                    example: authorization
                    type: string
                  message:
                    description: The error message.
                    example: Access token not set.
                    type: string
                  status:
                    description: The HTTP status code.
                    example: 403
                    type: integer
                  type:
                    description: The error type.
                    example: authentication_error
                    type: string
                required:
                - code
                - message
                - status
                - type
                title: AuthenticationError
                type: object
          description: Forbidden
      summary: Revoke access
      tags:
      - Providers
      x-ratelimit-tier: 2
  /v1/providers/ms-teams/{channel_id}/teams:
    get:
      callbacks: {}
      description: Get a list of teams belonging to the Microsoft Entra tenant. By default, archived and private channels are excluded from the results.
      operationId: listTeamsForMsTeamsProvider
      parameters:
      - description: The ID of the Knock Microsoft Teams channel to get teams for.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
      - description: A JSON encoded string containing the Microsoft Teams tenant object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: ms_teams_tenant_object
        required: true
        schema:
          type: string
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to filter teams.'
        example: displayName eq 'My Team'
        in: query
        name: query_options.$filter
        required: false
        schema:
          type: string
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to select fields on a team.'
        example: id,displayName,description
        in: query
        name: query_options.$select
        required: false
        schema:
          type: string
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to limit the number of teams returned.'
        example: 10
        in: query
        name: query_options.$top
        required: false
        schema:
          type: integer
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to retrieve the next page of results.'
        in: query
        name: query_options.$skiptoken
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamsForMsTeamsProviderResponse'
          description: OK
      summary: List teams
      tags:
      - Providers
      x-ratelimit-tier: 2
  /v1/providers/slack/{channel_id}/auth_check:
    get:
      callbacks: {}
      description: Check if a Slack channel is authenticated.
      operationId: slackProviderAuthCheck
      parameters:
      - description: The ID of the Knock Slack channel to check.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
      - description: A JSON encoded string containing the access token object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: access_token_object
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackAuthCheckResponse'
          description: OK
      summary: Check auth
      tags:
      - Providers
      x-ratelimit-tier: 2
  /v1/providers/slack/{channel_id}/channels:
    get:
      callbacks: {}
      description: List Slack channels for a Slack workspace.
      operationId: listChannelsForSlackProvider
      parameters:
      - description: The ID of the Knock Slack channel to get channels for.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
      - description: A JSON encoded string containing the access token object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: access_token_object
        required: true
        schema:
          type: string
      - description: Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request's response_metadata. Default value fetches the first "page" of the collection.
        in: query
        name: query_options.cursor
        required: false
        schema:
          type: string
      - description: The maximum number of channels to return. Defaults to 200.
        in: query
        name: query_options.limit
        required: false
        schema:
          type: integer
      - description: Set to true to exclude archived channels from the list. Defaults to `true` when not explicitly provided.
        in: query
        name: query_options.exclude_archived
        required: false
        schema:
          type: boolean
      - description: Mix and match channel types by providing a comma-separated list of any combination of public_channel, private_channel, mpim, im. Defaults to `"public_channel,private_channel"`. If the user's Slack ID is unavailable, this option is ignored and only public channels are returned.
        in: query
        name: query_options.types
        required: false
        schema:
          type: string
      - description: Encoded team ID (T1234) to list channels in, required if org token is used.
        in: query
        name: query_options.team_id
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelsForSlackProviderResponse'
          description: OK
        '403':
          content:
            application/json:
              schema:
                description: Authentication error response
                example:
                  code: authorization
                  message: Access token not set.
                  status: 403
                  type: authentication_error
                properties:
                  code:
                    description: The error code.
                    example: authorization
                    type: string
                  message:
                    description: The error message.
                    example: Access token not set.
                    type: string
                  status:
                    description: The HTTP status code.
                    example: 403
                    type: integer
                  type:
                    description: The error type.
                    example: authentication_error
                    type: string
                required:
                - code
                - message
                - status
                - type
                title: AuthenticationError
                type: object
          description: Forbidden
      summary: List channels
      tags:
      - Providers
      x-ratelimit-tier: 2
components:
  schemas:
    SlackAuthCheckResponse:
      description: The response from a Slack auth check request.
      example:
        connection:
          ok: true
      properties:
        connection:
          description: A Slack connection object.
          properties:
            ok:
              description: Whether the Slack connection is valid.
              type: boolean
            reason:
              description: The reason for the Slack connection if it is not valid.
              type:
              - string
              - 'null'
          required:
          - ok
          type: object
      required:
      - connection
      title: SlackAuthCheckResponse
      type: object
    ChannelsForSlackProviderResponse:
      description: The response from a Slack provider request, containing a list of channels.
      example:
        next_cursor: null
        slack_channels:
        - context_team_id: T01234567890
          id: C01234567890
          is_im: false
          is_private: false
          name: general
      properties:
        next_cursor:
          description: Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request's response_metadata. Default value fetches the first "page" of the collection.
          type:
          - string
          - 'null'
        slack_channels:
          description: List of Slack channels.
          items:
            description: A Slack channel.
            properties:
              context_team_id:
                description: The team ID that the Slack channel belongs to.
                type: string
              id:
                description: A Slack channel ID from the Slack provider.
                type: string
              is_im:
                description: Whether the Slack channel is an IM channel.
                type: boolean
              is_private:
                description: Whether the Slack channel is private.
                type: boolean
              name:
                description: Slack channel name.
                type: string
            required:
            - id
            - name
            - is_private
            - is_im
            - context_team_id
            type: object
          type: array
      required:
      - slack_channels
      - next_cursor
      title: ChannelsForSlackProviderResponse
      type: object
    MsTeamsAuthCheckResponse:
      description: The response from a Microsoft Teams auth check request.
      example:
        connection:
          ms_teams_tenant_id: a Microsoft Teams tenant ID
          ok: true
      properties:
        connection:
          description: A Microsoft Teams connection object.
          properties:
            ms_teams_tenant_id:
              description: The Microsoft Teams tenant ID for the connected tenant.
              type:
              - string
              - 'null'
            ok:
              description: Whether the Microsoft Teams connection is valid.
              type: boolean
            reason:
              description: The reason for the Microsoft Teams connection if it is not valid.
              type:
              - string
              - 'null'
          required:
          - ok
          type: object
      required:
      - connection
      title: MsTeamsAuthCheckResponse
      type: object
    ChannelsForMsTeamsProviderResponse:
      description: The response from a Microsoft Teams provider request, containing a list of channels.
      example:
        ms_teams_channels:
        - displayName: General
          id: channel-id-1
      properties:
        ms_teams_channels:
          description: List of Microsoft Teams channels.
          items:
            properties:
              createdDateTime:
                description: Microsoft Teams channel created date and time.
                type: string
              description:
                description: Microsoft Teams channel description.
                type:
                - string
                - 'null'
              displayName:
                description: Microsoft Teams channel name.
                type: string
              id:
                description: Microsoft Teams channel ID.
                type: string
              isArchived:
                description: Whether the Microsoft Teams channel is archived.
                type: boolean
              membershipType:
                description: Microsoft Teams channel membership type.
                type: string
            required:
            - id
            - displayName
            type: object
          type: array
      required:
      - ms_teams_channels
      title: ChannelsForMsTeamsProviderResponse
      type: object
    TeamsForMsTeamsProviderResponse:
      description: The response from a Microsoft Teams provider request, containing a list of teams.
      example:
        ms_teams_teams:
        - displayName: Engineering Team
          id: team-id-1
        skip_token: token-for-next-page
      properties:
        ms_teams_teams:
          description: List of Microsoft Teams teams.
          items:
            properties:
              description:
                description: Microsoft Teams team description.
                type:
                - string
                - 'null'
              displayName:
                description: Microsoft Teams team display name.
                type: string
              id:
                description: Microsoft Teams team ID.
                type: string
            required:
            - id
            - displayName
            type: object
          type: array
        skip_token:
          description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to retrieve the next page of results.'
          type:
          - string
          - 'null'
      required:
      - ms_teams_teams
      - skip_token
      title: TeamsForMsTeamsProviderResponse
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
x-provenance:
  method: harvested
  publisher: Knock
  source: https://knock.app/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)