> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hq.zone/llms.txt
> Use this file to discover all available pages before exploring further.

# List Microsoft Teams channels

> Lists the standard Teams channels HQ can post to (each with team_id, channel_id,
and name), sourced from the workspace corpus catalog the Teams crawl populates,
for use in pickers such as the schedule editor. The response includes a connected
flag that is false when the workspace has no active Teams installation, in which
case the channel list is empty. Scoped to the caller's workspace; requires the
agents:read scope.



## OpenAPI

````yaml GET /v1/api/teams/channels
openapi: 3.1.0
info:
  title: HQ API
  description: >-
    Public HTTP API for HQ. Authenticate with a Personal Access Token
    (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an
    OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's
    behalf. Both grant from the same resource:action scope vocabulary; an
    endpoint's required scope is listed under its `security`.
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  version: 1.0.0
servers:
  - url: https://api.hq.zone
    description: HQ API (production)
security: []
tags:
  - name: me
    description: The signed-in user's own account
  - name: conversations
    description: Conversations and their messages
  - name: documents
    description: The content-addressed documents library
  - name: schedules
    description: Scheduled prompts and recurring tasks
  - name: agents
    description: Agents, their skills and integrations
  - name: memory
    description: What the assistant remembers (L5 governance)
  - name: tokens
    description: Personal Access Token management
  - name: billing
    description: Usage and billing
  - name: notifications
    description: In-app notification center
  - name: admin
    description: Workspace administration
  - name: integrations
    description: Workspace integrations (Slack, MCP, skills)
  - name: onboarding
    description: New-workspace onboarding wizard
  - name: auth
    description: Sign-in, sessions, and OAuth
paths:
  /v1/api/teams/channels:
    get:
      tags:
        - integrations
      summary: List Microsoft Teams channels
      description: >-
        Lists the standard Teams channels HQ can post to (each with team_id,
        channel_id,

        and name), sourced from the workspace corpus catalog the Teams crawl
        populates,

        for use in pickers such as the schedule editor. The response includes a
        connected

        flag that is false when the workspace has no active Teams installation,
        in which

        case the channel list is empty. Scoped to the caller's workspace;
        requires the

        agents:read scope.
      operationId: list_teams_channels
      responses:
        '200':
          description: Standard Teams channels HQ can post to
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamsChannelsResp'
      security:
        - bearer_pat:
            - agents:read
        - oauth2:
            - agents:read
components:
  schemas:
    TeamsChannelsResp:
      type: object
      required:
        - connected
        - channels
      properties:
        channels:
          type: array
          items:
            $ref: '#/components/schemas/TeamsChannelJson'
        connected:
          type: boolean
          description: >-
            Whether this workspace has a live (non-revoked) Teams install with a
            known

            Connector serviceUrl - the same condition the schedule API enforces
            before

            persisting a Teams delivery target. `false` means the picker should
            prompt

            to connect Teams rather than show an (empty) list.
    TeamsChannelJson:
      type: object
      required:
        - team_id
        - channel_id
        - name
        - direct
      properties:
        channel_id:
          type: string
          description: >-
            The `19:...@thread.tacv2` channel id - the Connector conversation.id
            the

            delivery path posts a new root message into.
        direct:
          type: boolean
          description: >-
            `true` when HQ was explicitly ADDED to this channel (a private /
            shared

            channel captured from the bot channel-add event); `false` when it's
            a

            STANDARD channel reached automatically by the team install. The
            schedule

            picker ignores this; the admin Channels page groups by it.
        name:
          type: string
          description: Channel display name (e.g. "General").
        team_id:
          type: string
          description: >-
            AAD team (group) id - the first half of the corpus composite id.
            Carried

            so the schedule's `DeliverTo::TeamsChannel` is fully addressable.
  securitySchemes:
    bearer_pat:
      type: http
      scheme: bearer
      bearerFormat: hq_pat
      description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.'
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hq.zone/v1/oauth/authorize
          tokenUrl: https://api.hq.zone/v1/oauth/token
          refreshUrl: https://api.hq.zone/v1/oauth/token
          scopes:
            admin: Administer the workspace (users, settings, integrations)
            agents:read: View the agents in your workspace
            agents:write: Create and configure agents
            billing:read: View usage and billing information
            conversations:read: Read your conversations and their messages
            conversations:write: Start conversations and send messages on your behalf
            documents:read: Read your documents library
            documents:write: Upload and manage documents in your library
            memory:read: Read what the assistant remembers about you
            memory:write: Correct or delete what the assistant remembers
            schedules:read: View your scheduled tasks
            schedules:write: Create and manage scheduled tasks
            tables:read: Read your tables and their rows
            tables:write: Create tables and add, edit, or delete rows

````