openapi: 3.1.0
info:
  title: Boom CDP Custom Objects CDP People API
  version: 1.0.0
  description: 'Boom''s public REST API — one uniform surface over every platform capability. CDP: upsert people and custom objects, define object and relationship types, link and unlink relationships, and record behavioral events — one record per request or up to 1000 per request via the `/batch` endpoints. Segments: read (list, read, membership) and full authoring — discover the filterable catalog, validate a filter, create and update segments, preview match counts, and trigger evaluation. Initiatives: create and configure outreach initiatives, link WhatsApp templates, drive the lifecycle (launch, cancel, archive), and read collected-data summaries. Participants: enroll people into an active initiative, track their status, read conversation transcripts, and stop outreach. Journeys: read-only access to always-on message flows and their metrics. WhatsApp templates: list your WhatsApp numbers and list, read, and create message templates. The same capabilities are exposed as MCP tools with identical schemas.'
servers:
- url: https://www.useboom.ai
  description: Production
- url: https://dev.useboom.ai
  description: Development (sandbox — use a development organization API key)
security:
- bearerAuth: []
tags:
- name: CDP People
paths:
  /api/v1/cdp/people:
    get:
      operationId: cdp_people_list
      summary: List people
      description: List the organization's people, newest first.
      tags:
      - CDP People
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          $schema: https://json-schema.org/draft/2020-12/schema
          description: Max items to return, 1-1000 (default 100).
          type: integer
          minimum: 1
          maximum: 1000
      - name: cursor
        in: query
        required: false
        schema:
          $schema: https://json-schema.org/draft/2020-12/schema
          description: Opaque pagination token from a previous response's `next_cursor`. Omit for the first page.
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        externalId:
                          type: string
                          description: Your stable identifier for this person.
                        firstName:
                          anyOf:
                          - type: string
                          - type: 'null'
                        lastName:
                          anyOf:
                          - type: string
                          - type: 'null'
                        email:
                          anyOf:
                          - type: string
                          - type: 'null'
                        phoneNumber:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: E.164 format.
                        attributes:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties: {}
                          description: Free-form custom traits.
                        createdAt:
                          type: string
                          description: ISO 8601 timestamp.
                        updatedAt:
                          type: string
                          description: ISO 8601 timestamp.
                      required:
                      - externalId
                      - firstName
                      - lastName
                      - email
                      - phoneNumber
                      - attributes
                      - createdAt
                      - updatedAt
                      additionalProperties: false
                  next_cursor:
                    anyOf:
                    - type: string
                    - type: 'null'
                required:
                - data
                - next_cursor
                additionalProperties: false
        '400':
          description: Validation failed or the request cannot proceed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '404':
          description: The resource does not exist in this organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '409':
          description: Conflicts with the current state (duplicates, wrong lifecycle state).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '422':
          description: The request is well-formed but semantically invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '429':
          description: Rate limit exceeded — retry after `Retry-After`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '503':
          description: Transient error — retry with a narrower request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
    post:
      operationId: cdp_people_upsert
      summary: Upsert person
      description: Create or update a person by external id. Free-form attributes are fully replaced on each write.
      tags:
      - CDP People
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                externalId:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Your stable identifier for this person (idempotency key).
                firstName:
                  description: Given name.
                  anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                lastName:
                  description: Family name.
                  anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                email:
                  description: Email address.
                  anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                phoneNumber:
                  description: Phone number in E.164 format (e.g. +5215555555555).
                  anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                attributes:
                  description: Free-form custom traits (full-replace on upsert).
                  type: object
                  propertyNames:
                    type: string
                    maxLength: 255
                  additionalProperties: {}
              required:
              - externalId
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  externalId:
                    type: string
                  created:
                    type: boolean
                required:
                - externalId
                - created
                additionalProperties: false
        '400':
          description: Validation failed or the request cannot proceed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '404':
          description: The resource does not exist in this organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '409':
          description: Conflicts with the current state (duplicates, wrong lifecycle state).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '422':
          description: The request is well-formed but semantically invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '429':
          description: Rate limit exceeded — retry after `Retry-After`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '503':
          description: Transient error — retry with a narrower request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
  /api/v1/cdp/people/{externalId}:
    delete:
      operationId: cdp_people_delete
      summary: Delete person
      description: Soft-delete a person and their outgoing links. Idempotent; behavioral events are kept.
      tags:
      - CDP People
      parameters:
      - name: externalId
        in: path
        required: true
        schema:
          $schema: https://json-schema.org/draft/2020-12/schema
          type: string
          minLength: 1
          maxLength: 255
          description: The person externalId.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  removed:
                    type: boolean
                required:
                - removed
                additionalProperties: false
        '400':
          description: Validation failed or the request cannot proceed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '404':
          description: The resource does not exist in this organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '409':
          description: Conflicts with the current state (duplicates, wrong lifecycle state).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '422':
          description: The request is well-formed but semantically invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '429':
          description: Rate limit exceeded — retry after `Retry-After`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '503':
          description: Transient error — retry with a narrower request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
    get:
      operationId: cdp_people_get
      summary: Get person
      description: Read one person by their external id.
      tags:
      - CDP People
      parameters:
      - name: externalId
        in: path
        required: true
        schema:
          $schema: https://json-schema.org/draft/2020-12/schema
          type: string
          minLength: 1
          maxLength: 255
          description: The person externalId.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  externalId:
                    type: string
                    description: Your stable identifier for this person.
                  firstName:
                    anyOf:
                    - type: string
                    - type: 'null'
                  lastName:
                    anyOf:
                    - type: string
                    - type: 'null'
                  email:
                    anyOf:
                    - type: string
                    - type: 'null'
                  phoneNumber:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: E.164 format.
                  attributes:
                    type: object
                    propertyNames:
                      type: string
                    additionalProperties: {}
                    description: Free-form custom traits.
                  createdAt:
                    type: string
                    description: ISO 8601 timestamp.
                  updatedAt:
                    type: string
                    description: ISO 8601 timestamp.
                required:
                - externalId
                - firstName
                - lastName
                - email
                - phoneNumber
                - attributes
                - createdAt
                - updatedAt
                additionalProperties: false
        '400':
          description: Validation failed or the request cannot proceed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '404':
          description: The resource does not exist in this organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '409':
          description: Conflicts with the current state (duplicates, wrong lifecycle state).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '422':
          description: The request is well-formed but semantically invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '429':
          description: Rate limit exceeded — retry after `Retry-After`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '503':
          description: Transient error — retry with a narrower request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
  /api/v1/cdp/people/batch:
    post:
      operationId: cdp_people_batch_upsert
      summary: Batch upsert people
      description: Upsert up to 1000 people in one request. Idempotent and safely retryable.
      tags:
      - CDP People
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                items:
                  minItems: 1
                  maxItems: 1000
                  type: array
                  items:
                    type: object
                    properties:
                      externalId:
                        type: string
                        minLength: 1
                        maxLength: 255
                        description: Your stable identifier for this person (idempotency key).
                      firstName:
                        description: Given name.
                        anyOf:
                        - type: string
                          maxLength: 255
                        - type: 'null'
                      lastName:
                        description: Family name.
                        anyOf:
                        - type: string
                          maxLength: 255
                        - type: 'null'
                      email:
                        description: Email address.
                        anyOf:
                        - type: string
                          maxLength: 255
                        - type: 'null'
                      phoneNumber:
                        description: Phone number in E.164 format (e.g. +5215555555555).
                        anyOf:
                        - type: string
                          maxLength: 255
                        - type: 'null'
                      attributes:
                        description: Free-form custom traits (full-replace on upsert).
                        type: object
                        propertyNames:
                          type: string
                          maxLength: 255
                        additionalProperties: {}
                    required:
                    - externalId
                  description: People to upsert.
              required:
              - items
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  summary:
                    type: object
                    properties:
                      total:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      created:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      updated:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      failed:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                    required:
                    - total
                    - created
                    - updated
                    - failed
                    additionalProperties: false
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                          description: Zero-based index of the failed item.
                        externalId:
                          type: string
                        error:
                          type: object
                          properties:
                            code:
                              type: string
                              description: Stable machine-readable error code (snake_case).
                            message:
                              type: string
                          required:
                          - code
                          - message
                          additionalProperties: false
                      required:
                      - index
                      - error
                      additionalProperties: false
                required:
                - summary
                - errors
                additionalProperties: false
        '400':
          description: Validation failed or the request cannot proceed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '404':
          description: The resource does not exist in this organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '409':
          description: Conflicts with the current state (duplicates, wrong lifecycle state).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '422':
          description: The request is well-formed but semantically invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '429':
          description: Rate limit exceeded — retry after `Retry-After`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '503':
          description: Transient error — retry with a narrower request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
  /api/v1/cdp/people/search:
    get:
      operationId: cdp_people_search
      summary: Search people
      description: Search the organization's people by name, or a partial email / phone / externalId. Returns a relevance-ranked shortlist.
      tags:
      - CDP People
      parameters:
      - name: query
        in: query
        required: true
        schema:
          $schema: https://json-schema.org/draft/2020-12/schema
          type: string
          minLength: 2
          maxLength: 200
          description: A person name, or a partial email / phone / externalId. At least 2 characters.
      - name: limit
        in: query
        required: false
        schema:
          $schema: https://json-schema.org/draft/2020-12/schema
          description: Max matches to return, 1-25 (default 10).
          type: integer
          minimum: 1
          maximum: 25
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        externalId:
                          type: string
                          description: Your stable identifier for this person.
                        firstName:
                          anyOf:
                          - type: string
                          - type: 'null'
                        lastName:
                          anyOf:
                          - type: string
                          - type: 'null'
                        email:
                          anyOf:
                          - type: string
                          - type: 'null'
                        phoneNumber:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: E.164 format.
                        attributes:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties: {}
                          description: Free-form custom traits.
                        createdAt:
                          type: string
                          description: ISO 8601 timestamp.
                        updatedAt:
                          type: string
                          description: ISO 8601 timestamp.
                      required:
                      - externalId
                      - firstName
                      - lastName
                      - email
                      - phoneNumber
                      - attributes
                      - createdAt
                      - updatedAt
                      additionalProperties: false
                required:
                - data
                additionalProperties: false
        '400':
          description: Validation failed or the request cannot proceed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '404':
          description: The resource does not exist in this organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '409':
          description: Conflicts with the current state (duplicates, wrong lifecycle state).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '422':
          description: The request is well-formed but semantically invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '429':
          description: Rate limit exceeded — retry after `Retry-After`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '503':
          description: Transient error — retry with a narrower request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Organization API key, sent as `Authorization: Bearer boom_org_...`.'