openapi: 3.2.0
info:
  title: Bird Docs API
  version: 1.0.0
  description: 'The Bird API: one REST API for email, SMS, WhatsApp, verification, and

    Realtime.'
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: Docs
  description: Search our developer documentation.
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
components:
  schemas:
    DocsSearchResult:
      type: object
      additionalProperties: false
      required:
      - title
      - section
      - slug
      - url
      - doc_url
      - markdown_url
      - token_estimate
      - score
      properties:
        title:
          type: string
          minLength: 1
          readOnly: true
          description: Title of the documentation page this result belongs to.
        section:
          type: string
          minLength: 1
          readOnly: true
          description: Heading of the matching section within the page.
        slug:
          type: string
          minLength: 1
          readOnly: true
          description: Stable identifier of the page. Pass it as the `slug` parameter of `GET /v1/docs/pages` to read the whole page as Markdown.
        url:
          type: string
          minLength: 1
          readOnly: true
          description: Absolute URL of the matching section, including the heading anchor.
        doc_url:
          type: string
          minLength: 1
          readOnly: true
          description: Absolute URL of the page, without the section anchor. Results from the same page share it, so it can be used to group them.
        markdown_url:
          type: string
          minLength: 1
          readOnly: true
          description: Absolute URL that returns the page's full content as Markdown; also the page's canonical source URL.
        snippet:
          type: string
          readOnly: true
          description: Short excerpt of the matching content, with the query terms in context. Always returned.
        highlights:
          type: array
          readOnly: true
          description: The passages of the section that match the query, longer than the snippet. Returned only when `contents` is `highlights`.
          items:
            type: string
        token_estimate:
          type: integer
          readOnly: true
          description: Approximate token count of the full page returned by `markdown_url`, to budget reading it. Results from the same page share it.
        score:
          type: number
          readOnly: true
          description: Relevance score. Higher is more relevant; results are ordered by descending score.
    DocsPage:
      type: object
      additionalProperties: false
      required:
      - slug
      - locale
      - url
      - markdown
      properties:
        slug:
          type: string
          minLength: 1
          readOnly: true
          description: Slug of the page, echoing the requested slug.
        locale:
          type: string
          minLength: 1
          readOnly: true
          description: Documentation locale the page was drawn from.
        url:
          type: string
          minLength: 1
          readOnly: true
          description: Absolute URL of the page, suitable to cite as the source of an answer.
        markdown:
          type: string
          minLength: 1
          readOnly: true
          description: The page's full content as Markdown.
    DocsSearchResponse:
      type: object
      additionalProperties: false
      required:
      - query
      - locale
      - results
      properties:
        query:
          type: string
          minLength: 1
          readOnly: true
          description: The search query that produced these results.
        locale:
          type: string
          minLength: 1
          readOnly: true
          description: The documentation locale the results were drawn from.
        results:
          type: array
          readOnly: true
          description: Matching documentation sections, ordered by descending relevance.
          items:
            $ref: '#/components/schemas/DocsSearchResult'
    ErrorBody:
      type: object
      additionalProperties: false
      required:
      - type
      - code
      - name
      - message
      - doc_url
      - request_id
      properties:
        type:
          type: string
          minLength: 1
          description: Broad category for coarse client branching.
          enum:
          - auth_error
          - bad_request_error
          - billing_error
          - conflict_error
          - gone_error
          - internal_error
          - misdirected_error
          - not_found_error
          - not_implemented_error
          - payload_too_large_error
          - permission_error
          - precondition_error
          - rate_limit_error
          - service_unavailable_error
          - too_early_error
          - validation_error
        code:
          type: string
          minLength: 1
          pattern: ^E\d{5}$
          description: Opaque, stable, unique error identifier. Never reused.
        name:
          type: string
          minLength: 1
          description: Human-readable slug for log readability. Paired with code, never replaces it.
        message:
          type: string
          minLength: 1
          description: Human-readable description. Not stable; clients must not parse it.
        param:
          type: string
          minLength: 1
          description: Identifies the offending field. Omitted when not applicable.
        doc_url:
          type: string
          minLength: 1
          format: uri
          description: Stable link to the docs page for this error code.
        request_id:
          type: string
          minLength: 1
          description: Request correlation ID for support and troubleshooting. Also returned in the `X-Request-Id` response header.
        vendor_code:
          type: string
          minLength: 1
          description: 'Verbatim error code from an external system, such as an SMTP response code or a payment decline code. Present only when the code may help you resolve the error.

            '
        details:
          type: array
          description: Per-field validation errors. Present only on validation_error responses.
          items:
            $ref: '#/components/schemas/ErrorDetail'
        remediation:
          type: string
          minLength: 1
          description: A human-readable next step to resolve this error. Present when a recovery is known.
        next:
          type: array
          description: 'The steps that resolve this error. Perform them in order, re-reading after each; a `wait` or `terminal` step is always last. Present for errors with a well-defined recovery, such as unmet preconditions and conflicts.

            '
          items:
            $ref: '#/components/schemas/NextAction'
    ErrorDetail:
      type: object
      additionalProperties: false
      required:
      - param
      - message
      properties:
        param:
          type: string
          minLength: 1
          description: 'Dotted field path, such as `to[0].email`, `subject`, or `.`. When the request was rejected for a query parameter the endpoint does not declare, this carries that parameter''s name instead of a field path.

            '
        message:
          type: string
          minLength: 1
          description: What is wrong with this field.
    NextAction:
      type: object
      additionalProperties: false
      required:
      - kind
      - description
      properties:
        kind:
          type: string
          minLength: 1
          x-extensible-enum:
          - operation
          - external
          - wait
          - terminal
          description: "What you do about this step.\n\n- `operation`: call the operation named in `operation`, then\n  read again.\n- `external`: act somewhere this API does not reach, then read\n  again.\n- `wait`: nothing is asked of you, so read again later.\n- `terminal`: nothing you do resolves this, so stop retrying.\n\nTolerate a value you do not recognize: show the `description` and\noffer no action.\n"
        description:
          type: string
          minLength: 1
          description: A short, human-readable label for the step, suitable for display.
        operation:
          type: string
          minLength: 1
          description: 'The operationId to call. Present only when `kind` is `operation`. The operation''s own schema says how to call it; this says only which one, and what to address it with.

            '
        params:
          type: object
          additionalProperties:
            type: string
            minLength: 1
          description: 'The parameters that address the operation, by name: `{"sender_id": "…"}` for an operation on `/v1/sms/senders/{sender_id}/requirements`. A parameter the operation takes in its query string is given the same way, so an operation addressed as `?subject_id=` carries `{"subject_id": "…"}`. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when `kind` is `operation` and the operation names a subject. A request body, when the operation takes one, is described by the operation''s own schema and never appears here.

            '
        url:
          type: string
          format: uri
          description: 'A URL to open. Present only when `kind` is `external`, and only when the step has one. An external step whose `description` says to go and do something with no URL to open is normal.

            '
    Error:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
  headers:
    RateLimit:
      description: 'Remaining capacity for the request''s rate-limit policy as an IETF Structured Field. Format: `"<policy>";r=<remaining>;t=<seconds_until_reset>`.

        '
      schema:
        type: string
      example: '"email_send";r=842;t=35'
    RateLimit-Policy:
      description: 'Effective quota for the request''s rate-limit policy as an IETF Structured Field. Format: `"<policy>";q=<quota>;w=<window_seconds>`.

        '
      schema:
        type: string
      example: '"email_send";q=1000;w=60'
    RetryAfter:
      description: 'Number of seconds to wait before retrying the request.

        '
      schema:
        type: integer
        minimum: 0
      example: 35
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: 'The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

        '
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unprocessable:
      description: 'The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Pass the API key as a bearer token in the `Authorization` header. Keys use

        the format `bk_{region}_*`. The prefix identifies the region and selects the

        API endpoint. Official Bird SDKs and the CLI derive the region from the key.

        '
    CookieAuth:
      type: apiKey
      in: cookie
      name: bird_session
      description: 'Session cookie set after signing in to the Bird dashboard. The cookie

        value is an opaque session token; no session data is stored in the cookie

        itself.

        '
    RealtimeKey:
      type: apiKey
      in: header
      name: X-Realtime-Key
      description: 'The Realtime app key. Together with `X-Realtime-Secret`, it authenticates a

        request to the Realtime API in addition to the workspace credential. Both

        values come from the app''s credentials and must belong to the calling

        workspace. Official Bird SDKs accept the pair as client configuration.

        '
    RealtimeSecret:
      type: apiKey
      in: header
      name: X-Realtime-Secret
      description: 'The Realtime app secret paired with `X-Realtime-Key`. The API returns the

        secret only when the key is created and does not store it. Create a new key

        and revoke the current key if you lose the secret. Official Bird SDKs accept

        the pair as client configuration.

        '