Bird API

openapi: 3.1.0
info:
  title: Bird API
  version: 1.0.0
  description: |
    The Bird API: one REST API for email, SMS, WhatsApp, verification, and
    Realtime. Manage workspaces, organizations, teams, sending domains,
    dedicated IPs, suppressions, contacts and audiences, and outbound message
    delivery across every channel.

    Setting a `User-Agent` header is recommended but not required. Official Bird
    SDKs set it automatically (format: `bird-<language>/<version>`). The header is
    used for operational logging and customer-support diagnostics; the API never
    rejects requests that omit it.

    Rate limits are advertised on every response from a rate-limited endpoint as
    IETF `RateLimit` and `RateLimit-Policy` headers (Structured Fields per RFC
    9651; spec draft-ietf-httpapi-ratelimit-headers-11). On 429 responses, a
    `Retry-After` header in seconds is also returned. Clients should pace
    themselves against the `r` (remaining) and `t` (seconds until reset) params
    in the `RateLimit` header rather than only reacting to 429s.

    The full API reference is at https://bird.com/docs/api, and the guides and
    official SDKs at https://bird.com/docs.
servers:
  - url: https://{region}.platform.bird.com
    description: |
      Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.
    variables:
      region:
        default: us1
        enum:
          - us1
          - eu1
        description: The region your organization's data is hosted in.
  - url: https://platform.bird.com
    description: Region-independent endpoint for authentication and account administration.
  - url: http://localhost:8080
    description: Local development.
security:
  - BearerAuth: []
tags:
  - name: workspaces
    description: Workspace management.
  - name: realtime-apps
    description: Realtime app management.
  - name: realtime-events
    description: |
      Publish events to a Realtime app's channels from your server (the data plane). Sending to several channels at once broadcasts to all of them.
  - name: email-messages
    description: |
      Send emails to recipients you address explicitly in `to`, `cc`, and `bcc`. Use this for transactional sends (receipts, password resets, alerts) and for marketing sends where you already have the recipient addresses on hand. The same endpoint accepts every content type. Set `category` to control suppression policy.
  - name: email-broadcasts
    description: |
      Send one email to a stored audience. Create a broadcast as a draft, then send it immediately or schedule it for later; scheduled and in-progress broadcasts can be canceled. The audience's contacts at send time become the recipient set after suppressions are applied. The recipients endpoint returns each recipient's delivery state.
  - name: email-contacts
    description: |
      Contacts are the people you send broadcasts to. Each contact is unique by email address within a workspace and carries optional name fields and custom properties for personalization. Custom properties are defined once per workspace via the contact properties API and then set per contact.
  - name: email-audiences
    description: |
      Audiences are the recipient lists broadcasts are sent to. An audience holds a set of contacts that you manage through the API. The contacts in the audience at send time become the broadcast's recipients after suppressions are applied. A contact can belong to multiple audiences.
  - name: email-stats
    description: Email analytics, including daily and hourly delivery statistics, tag breakdowns, and a KPI summary.
  - name: sms-messages
    description: |
      Send SMS messages to recipients you address by phone number, and read their delivery status and lifecycle events. Each message is one recipient and one body; set `category` to control opt-out policy and per-country compliance.
  - name: sms-templates
    description: Create and publish multilingual workspace SMS templates and browse built-in templates. Published workspace versions preserve their language content; built-in versions reflect the current catalogue.
  - name: sms-stats
    description: SMS analytics, including daily and hourly lifecycle counts, dimension breakdowns, and a KPI summary.
  - name: verify-verifications
    description: |
      Send a one-time passcode to a recipient and check the code they enter. Create a verification to send a passcode over email or SMS, then submit the recipient's code to verify it.
  - name: whatsapp-messages
    description: |
      Send WhatsApp messages, whether a template, free-form content, or interactive content the recipient can tap, and read the messages your workspace sent and received, including their current delivery status and lifecycle events.
  - name: whatsapp-templates
    description: |
      Browse the WhatsApp message templates available to your workspace, approved by Meta and ready to send.
  - name: whatsapp-stats
    description: WhatsApp analytics, including daily and hourly delivery statistics and a KPI summary.
  - name: domains
    description: Sending domain management and DNS verification.
  - name: email-suppressions
    description: Email suppression list management.
  - name: email-templates
    description: |
      Reusable email templates and their versions, with stored subject, HTML, and plain-text content you manage and reference when sending.
  - name: email-inbound-addresses
    description: |
      Addresses generated for receiving mail. Forward a mailbox to an inbound address to parse each message into a received email.
  - name: email-inbound-messages
    description: |
      Emails received on your behalf, including each parsed message, its body, raw MIME content, and attachments.
  - name: email-mailboxes
    description: |
      Durable mailbox identities for agents. A mailbox owns an address, applies receive policy through allow/block rules, and remembers conversations for its retention tier.
  - name: email-inbound-routes
    description: |
      Routing rules that direct inbound mail on your domains into mailboxes, or drop it, in priority order.
  - name: email-threads
    description: |
      Conversations in a mailbox. Threads group related inbound and outbound messages and carry read state, labels, and participants.
  - name: email-smtp-configs
    description: |
      Default IP pool, category, tags, and open and click tracking settings for messages submitted over SMTP with a given API key.
  - name: webhooks
    description: Webhook endpoint management.
  - name: numbers
    description: Phone number catalog and purchasing.
  - name: docs
    description: Search our developer documentation.
  - name: voice-calls
    description: Call records (CDR) for the workspace, in flight and completed.
  - name: whatsapp-numbers
    description: |
      Connect phone numbers from Meta's embedded signup flow and check their WhatsApp setup status.
  - name: whatsapp-business-accounts
    description: |
      Read the WhatsApp Business Accounts your workspace has connected, so a template can be created on the account you choose.
  - name: sms-keyword-rules
    description: |
      Manage the response when someone sends a keyword to one of your numbers. Each supported country starts with opt-out, opt-in, and help keywords. Create a rule to replace a default response or add campaign keywords.
  - name: lookup
    description: |
      Inspect a recipient before sending. Phone-number lookups return carrier, portability, number type, reachability, roaming, SIM-change, and fraud-risk data when requested. Email lookups return deliverability, confidence, failure reasons, and suggested corrections for likely misspellings.
  - name: sms-suppressions
    description: Sender and subscriber pairs that block SMS delivery.
  - name: email-competitive
    description: |
      Watch competitor brands and see how their email compares with yours. Figures about a competitor are estimates from an email panel, which observes a sample of real inboxes; figures about your own sending are counted rather than estimated wherever that is possible.
  - name: preferences
    description: Stated messaging preferences (consent grants and opt-outs) recorded per handle across email, SMS, and WhatsApp, with causally ordered writes.
  - name: email-inbox-insights
    description: |
      Inbox placement, seed tests, and sending reputation for the workspace's
      own sending domains, measured from a panel of real mailboxes.

      Rates here are percentages carrying a `_percent` suffix (`87.4`).
      Competitive Insights reports the same kind of figure as a fraction
      (`0.874`), so a client reading both products scales one of them.
  - name: whatsapp-keyword-rules
    description: |
      What happens when someone replies STOP or START to a WhatsApp message: the keywords Bird ships, the keywords you add, and the replies you send back.
paths:
  /v1/docs/search:
    get:
      operationId: getDocsSearch
      summary: Get documentation search results
      description: |
        Searches the documentation and returns matching sections, best match first. Each result links to its section heading and includes the page's `slug`; read the full page with `GET /v1/docs/pages`.

        No authentication is required. A blank query returns `400`, and `503` means search is temporarily unavailable.
      tags:
        - docs
      security: []
      x-audiences:
        - public
        - command
      parameters:
        - name: q
          in: query
          required: true
          description: The text to search the documentation for. Must not be blank.
          schema:
            type: string
            minLength: 1
        - name: locale
          in: query
          required: false
          description: Documentation locale to search, as a language-region code such as `en-us`. Defaults to `en-us` when omitted or unavailable.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return (1–25).
          schema:
            type: integer
            minimum: 1
            maximum: 25
            default: 10
        - name: contents
          in: query
          required: false
          description: How much of each matching section to return. `snippet` (the default) returns a short preview; `highlights` additionally returns the passages that match the query. For the full text, fetch a result's `markdown_url`.
          schema:
            type: string
            enum:
              - snippet
              - highlights
            default: snippet
      responses:
        '200':
          description: Ranked search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocsSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
        - cli
        - mcp
        - n8n
  /v1/docs/pages:
    get:
      operationId: getDocsPage
      summary: Get a documentation page
      description: |
        Returns the full Markdown content of a documentation page. Get its `slug` from `GET /v1/docs/search`, or pass `index` for the documentation landing page.

        No authentication is required. An unknown slug returns `404`, and `503` means the documentation backend is temporarily unavailable.
      tags:
        - docs
      security: []
      x-audiences:
        - public
        - command
      parameters:
        - name: slug
          in: query
          required: true
          description: Slug of the page to read, as returned in the `slug` field of a search result (for example `guides/email/contacts`). Use `index` for the documentation landing page.
          schema:
            type: string
            minLength: 1
        - name: locale
          in: query
          required: false
          description: Documentation locale to read, as a language-region code such as `en-us`. Defaults to `en-us` when omitted or unavailable.
          schema:
            type: string
      responses:
        '200':
          description: The documentation page content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocsPage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
        - cli
        - mcp
        - n8n
  /v1/workspace:
    get:
      operationId: getCurrentWorkspace
      summary: Get the current workspace
      description: |
        Returns the workspace the current credentials are scoped to: its ID, name, the ID of the organization that owns it, and its notification and logo settings. The organization's own name and members are not included. Requires at least read access to the workspace.
      tags:
        - workspaces
      security:
        - BearerAuth: []
        - CookieAuth: []
      x-audiences:
        - public
        - command
      x-snippet-key: workspace.get
      responses:
        '200':
          description: The current workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
        - cli
        - make
        - mcp
        - n8n
        - sdk
  /v1/realtime/regions:
    get:
      operationId: listRealtimeRegions
      x-snippet-key: none
      summary: List Realtime regions
      description: Returns the regions a Realtime app can be created in. Use one of these identifiers as the `region` when creating an app.
      tags:
        - realtime-apps
      security:
        - BearerAuth: []
        - CookieAuth: []
      x-audiences:
        - public
        - command
      parameters:
        - $ref: '#/components/parameters/XWorkspaceId'
      responses:
        '200':
          description: The available Realtime regions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeRegionList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
        - cli
        - mcp
        - n8n
  /v1/realtime/apps:
    post:
      operationId: createRealtimeApp
      x-snippet-key: none
      summary: Create a Realtime app
      description: Provisions a new Realtime app for the workspace and returns it with the initial key. Store the key secret when you receive it because later responses do not include it. If you lose the secret, create a new key and revoke this one.
      tags:
        - realtime-apps
      security:
        - BearerAuth: []
        - CookieAuth: []
      x-audiences:
        - public
        - command
      parameters:
        - $ref: '#/components/parameters/XWorkspaceId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeAppCreate'
      responses:
        '201':
          description: Realtime app created. Includes the initial key's one-time secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeAppCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
        - cli
        - mcp
        - n8n
    get:
      operationId: listRealtimeApps
      x-snippet-key: none
      summary: List Realtime apps
      description: |
        Returns the workspace's Realtime apps as a paginated list, filterable by a case-insensitive `name` substring. Each entry carries the app's configuration and connection details (`app_id`, `region`) but never key secrets. Use [List a Realtime app's keys](/docs/api/reference/list-realtime-app-keys) and [Create a Realtime app key](/docs/api/reference/create-realtime-app-key) to manage them.
      tags:
        - realtime-apps
      security:
        - BearerAuth: []
        - CookieAuth: []
      x-audiences:
        - public
        - command
      parameters:
        - $ref: '#/components/parameters/XWorkspaceId'
        - name: name
          in: query
          required: false
          description: Substring match against the app name (case-insensitive).
          schema:
            type: string
        - name: sort
          in: query
          required: false
          description: Field to sort by.
          schema:
            $ref: '#/components/schemas/RealtimeAppSortField'
        - $ref: '#/components/parameters/OrderDesc'
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/StartingAfter'
        - $ref: '#/components/parameters/EndingBefore'
        - $ref: '#/components/parameters/IncludeTotal'
      responses:
        '200':
          description: Paginated list of Realtime apps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeAppList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
        - cli
        - mcp
        - n8n
  /v1/realtime/apps/{realtime_app_id}:
    parameters:
      - name: realtime_app_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/RealtimeAppID'
        description: ID of the Realtime app (`rap_` prefix), as returned when the app was created.
    get:
      operationId: getRealtimeApp
      x-snippet-key: none
      summary: Get a Realtime app
      description: |
        Returns a single Realtime app with its configuration and connection details (`app_id`, `region`). Key secrets are never included; use [List a Realtime app's keys](/docs/api/reference/list-realtime-app-keys) to manage them. Returns a `404 Not Found` error if the app does not exist in the workspace.
      tags:
        - realtime-apps
      security:
        - BearerAuth: []
        - CookieAuth: []
      x-audiences:
        - public
        - command
      parameters:
        - $ref: '#/components/parameters/XWorkspaceId'
      responses:
        '200':
          description: Realtime app with its current configuration and status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeApp'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
        - cli
        - mcp
        - n8n
    patch:
      operationId: updateRealtimeApp
      x-snippet-key: none
      summary: Update a Realtime app
      description: Updates a Realtime app's name and configuration flags. Region is immutable; TLS is always enforced. Omitted fields are left unchanged.
      tags:
        - realtime-apps
      security:
        - BearerAuth: []
        - CookieAuth: []
      x-audiences:
        - public
        - command
      parameters:
        - $ref: '#/components/parameters/XWorkspaceId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeAppUpdate'
      responses:
        '200':
          description: The updated Realtime app.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeApp'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
        - cli
        - mcp
        - n8n
    delete:
      operationId: deleteRealtimeApp
      x-snippet-key: none
      summary: Delete a Realtime app
      description: 'Permanently deletes the app: disconnects all clients and removes its keys and configuration. This cannot be undone.'
      tags:
        - realtime-apps
      security:
        - BearerAuth: []
        - CookieAuth: []
      x-audiences:
        - public
        - command
      parameters:
        - $ref: '#/components/parameters/XWorkspaceId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: The app was deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
        - cli
        - mcp
        - n8n
  /v1/realtime/apps/{realtime_app_id}/events:
    parameters:
      - name: realtime_app_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/RealtimeAppID'
        description: ID of the Realtime app (`rap_` prefix), as returned when the app was created.
    post:
      operationId: publishRealtimeAppEvent
      x-snippet-key: realtime.publish
      summary: Publish a Realtime event
      description: Publishes an event to one or more channels of a Realtime app. Listing several channels broadcasts the event to all of them in one call. Connected clients subscribed to those channels receive it in real time.
      tags:
        - realtime-events
      security:
        - BearerAuth: []
          RealtimeKey: []
          RealtimeSecret: []
        - CookieAuth: []
          RealtimeKey: []
          RealtimeSecret: []
      x-audiences:
        - public
      parameters:
        - $ref: '#/components/parameters/XWorkspaceId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimePublish'
            examples:
              onboarding-realtime:
                summary: The first publish from the dashboard's onboarding step
                value:
                  event: order-updated
                  channels:
                    - orders
                  data:
                    id: 42
                    status: shipped
      responses:
        '200':
          description: The event was accepted for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimePublishResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
        - make
        - sdk
  /v1/realtime/apps/{realtime_app_id}/batch-events:
    parameters:
      - name: realtime_app_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/RealtimeAppID'
        description: ID of the Realtime app (`rap_` prefix), as returned when the app was created.
    post:
      operationId: publishRealtimeAppBatch
      x-snippet-key: realtime.publishBatch
      summary: Publish a batch of Realtime events
      description: Publishes up to 10 events (each to one channel) in a single request.
      tags:
        - realtime-events
      security:
        - BearerAuth: []
          RealtimeKey: []
          RealtimeSecret: []
        - CookieAuth: []
          RealtimeKey: []
          RealtimeSecret: []
      x-audiences:
        - public
      parameters:
        - $ref: '#/components/parameters/XWorkspaceId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeBatchPublish'
      responses:
        '200':
          description: The events were accepted for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeBatchPublishResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
        - make
        - sdk
  /v1/realtime/apps/{realtime_app_id}/channels:
    parameters:
      - name: realtime_app_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/RealtimeAppID'
        description: ID of the Realtime app (`rap_` prefix), as returned when the app was created.
    get:
      operationId: listRealtimeAppChannels
      x-snippet-key: realtime.channels.list
      summary: List Realtime channels
      description: Lists the app's currently occupied channels, optionally filtered by name prefix.
      tags:
        - realtime-events
      security:
        - BearerAuth: []
          RealtimeKey: []
          RealtimeSecret: []
        - CookieAuth: []
          RealtimeKey: []
          RealtimeSecret: []
      x-audiences:
        - public
      parameters:
        - $ref: '#/components/parameters/XWorkspaceId'
        - name: prefix
          in: query
          required: false
          description: Only channels whose name starts with this prefix (for example, `presence-`).
          schema:
            type: string
        - name: include
          in: query
          required: false
          description: Per-channel attributes to include. Repeatable. Requesting `member_count` without a presence-channel `prefix`, or `connection_count` when the app's connection-counting flag is off, returns a validation error (400).
          schema:
            type: array
            items:
              $ref: '#/components/schemas/RealtimeChannelInclude'
      responses:
        '200':
          description: The occupied channels.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeChannelsList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
        - make
        - sdk
  /v1/realtime/apps/{realtime_app_id}/channels/{channel_name}:
    parameters:
      - name: realtime_app_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/RealtimeAppID'
        description: ID of the Realtime app (`rap_` prefix), as returned when the app was created.
      - name: channel_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/RealtimeChannelName'
        description: Name of the Realtime channel to retrieve.
    get:
      operationId: getRealtimeAppChannel
      x-snippet-key: realtime.channels.get
      summary: Get a Realtime channel
      description: 'Returns a single channel''s occupancy and optional counts. A channel appears when its first connection subscribes and disappears when its last connection leaves. An unknown or unused name returns `200 OK` with `occupied: false`.'
      tags:
        - realtime-events
      security:
        - BearerAuth: []
          RealtimeKey: []
          RealtimeSecret: []
        - CookieAuth: []
          RealtimeKey: []
          RealtimeSecret: []
      x-audiences:
        - public
      parameters:
        - $ref: '#/components/parameters/XWorkspaceId'
        - name: include
          in: query
          required: false
          description: Attributes to include. Repeatable. Requesting `member_count` for a non-presence channel, or `connection_count` when the app's connection-counting flag is off, returns a validation error (400).
          schema:
            type: array
            items:
              $ref: '#/components/schemas/RealtimeChannelInclude'
      responses:
        '200':
          description: The channel state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeChannelInfo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
   

# --- truncated at 32 KB (4697 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/messagebird/refs/heads/main/openapi/messagebird-bird-api-openapi.yml