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

# Create a large task

> Create a task for up to 100000 SMS or call recipients. Options use the existing batch fields. No messages or calls are sent until all chunks are uploaded and start is requested. upload_chunk_size defaults to 1000; choose a smaller value for large per-recipient variables. Every request must fit the 1 MiB JSON limit.



## OpenAPI

````yaml /openapi/openapi.yaml post /bulk-tasks
openapi: 3.1.0
info:
  title: Brightalk Public API
  version: '2026-07-16'
  description: >-
    Server-to-server REST API for AI calls, batch dialing, and dashboard-managed
    Automation definitions.
  license:
    name: Brightalk API Terms
    identifier: LicenseRef-Brightalk-API
servers:
  - url: https://api.brightalk.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: Eligible dashboard-managed AI voice agents.
  - name: Automations
    description: Dashboard-managed Automation summaries.
  - name: Contacts
    description: Organization contacts and external identities.
  - name: Calls
    description: Immediate asynchronous AI calls and their scalar results.
  - name: Batches
    description: Draft, schedule, and control aggregate batch dialing.
  - name: Automation runs
    description: Create and control one-contact Automation runs.
  - name: Recordings
    description: Metadata and short-lived signed download URLs for call recordings.
  - name: LINE messages
    description: Send text to linked contacts and retrieve send receipts.
paths:
  /bulk-tasks:
    post:
      tags:
        - Batches
      summary: Create a large task
      description: >-
        Create a task for up to 100000 SMS or call recipients. Options use the
        existing batch fields. No messages or calls are sent until all chunks
        are uploaded and start is requested. upload_chunk_size defaults to 1000;
        choose a smaller value for large per-recipient variables. Every request
        must fit the 1 MiB JSON limit.
      operationId: createBulkTask
      parameters:
        - $ref: '#/components/parameters/BrightalkVersion'
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBulkTaskRequest'
      responses:
        '201':
          description: Task state returned. Submission is not delivery or completion.
          headers:
            Brightalk-Version:
              $ref: '#/components/headers/Brightalk-Version'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            Idempotency-Replayed:
              $ref: '#/components/headers/Idempotency-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkTask'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/RequestTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request POST 'https://api.brightalk.ai/bulk-tasks' \
              --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
              --header "Brightalk-Version: 2026-07-16" \
              --header "Content-Type: application/json" \
              --header "Idempotency-Key: bulk-example-1" \
              --data '{"kind":"sms","total_recipients":10000,"recipient_format":"recipients","upload_chunk_size":1000,"options":{"message":"Hello {{name}}","test_mode":true}}'
        - lang: javascript
          label: JavaScript
          source: >-
            const response = await fetch("https://api.brightalk.ai/bulk-tasks",
            {
              method: "POST",
              headers: {
                "Authorization": `Bearer ${process.env.BRIGHTALK_API_KEY}`,
                "Brightalk-Version": "2026-07-16",
                "Content-Type": "application/json",
                "Idempotency-Key": "bulk-example-1"
              },
              body: JSON.stringify({"kind":"sms","total_recipients":10000,"recipient_format":"recipients","upload_chunk_size":1000,"options":{"message":"Hello {{name}}","test_mode":true}}),
            });

            console.log(response.status, await response.json());
        - lang: python
          label: Python
          source: |-
            import os
            import requests

            response = requests.request(
                "POST",
                "https://api.brightalk.ai/bulk-tasks",
                headers={
                    "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
                    "Brightalk-Version": "2026-07-16",
                    "Content-Type": "application/json",
                    "Idempotency-Key": "bulk-example-1"
                },
                json={"kind":"sms","total_recipients":10000,"recipient_format":"recipients","upload_chunk_size":1000,"options":{"message":"Hello {{name}}","test_mode":True}},
            )
            print(response.status_code, response.json())
components:
  parameters:
    BrightalkVersion:
      name: Brightalk-Version
      in: header
      required: false
      description: >-
        Selects the date-based API version. Omission uses the organization’s
        pinned default.
      schema:
        type: string
        const: '2026-07-16'
        default: '2026-07-16'
    XRequestId:
      name: X-Request-Id
      in: header
      required: false
      description: >-
        A caller-generated correlation value matching [A-Za-z0-9._:-]{1,64}.
        Invalid values are replaced.
      schema:
        type: string
        pattern: ^[A-Za-z0-9._:-]{1,64}$
        maxLength: 64
    IdempotencyKeyRequired:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        A nonsecret key retained for 24 hours. Reuse only for a semantically
        identical request.
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^(?=.{1,255}$)[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$
  schemas:
    CreateBulkTaskRequest:
      oneOf:
        - type: object
          properties:
            kind:
              type: string
              const: calls
            total_recipients:
              type: integer
              minimum: 1
              maximum: 100000
            upload_chunk_size:
              default: 1000
              type: integer
              minimum: 1
              maximum: 1000
            recipient_format:
              type: string
              enum:
                - contact_ids
                - recipients
            options:
              type: object
              properties:
                variables:
                  type: object
                  propertyNames:
                    type: string
                    pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$
                  additionalProperties:
                    type: string
                    maxLength: 2000
                metadata:
                  type: object
                  propertyNames:
                    type: string
                    pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$
                  additionalProperties:
                    type: string
                    maxLength: 512
                reference_id:
                  type: string
                  minLength: 1
                  maxLength: 255
                external_id:
                  type: string
                  minLength: 1
                  maxLength: 255
                missing_variables:
                  type: object
                  properties:
                    mode:
                      type: string
                      enum:
                        - reject
                        - default
                    defaults:
                      type: object
                      propertyNames:
                        type: string
                        pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$
                      additionalProperties:
                        type: string
                        maxLength: 2000
                  required:
                    - mode
                  additionalProperties: false
                webhook:
                  type: object
                  properties:
                    url:
                      type: string
                      maxLength: 2048
                      format: uri
                    secret:
                      type: string
                      minLength: 32
                      maxLength: 256
                      pattern: ^[\x21-\x7e]+$
                  required:
                    - url
                    - secret
                  additionalProperties: false
                test_mode:
                  type: boolean
                retry_policy:
                  type: object
                  properties:
                    max_retries:
                      type: integer
                      minimum: 0
                      maximum: 5
                    delay_minutes:
                      type: integer
                      minimum: 1
                      maximum: 1440
                    'on':
                      minItems: 1
                      maxItems: 2
                      type: array
                      items:
                        type: string
                        enum:
                          - no_answer
                          - busy
                  required:
                    - max_retries
                    - delay_minutes
                    - 'on'
                  additionalProperties: false
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                agent_id:
                  type: string
                  format: uuid
                  pattern: >-
                    ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                schedule:
                  type: object
                  properties:
                    start_at:
                      type: string
                      allOf:
                        - pattern: >-
                            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                        - pattern: >-
                            ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$
                    calling_window:
                      type: object
                      properties:
                        time_zone:
                          type: string
                          enum:
                            - Asia/Taipei
                            - Asia/Hong_Kong
                            - Asia/Shanghai
                            - Asia/Tokyo
                            - Asia/Seoul
                            - Asia/Singapore
                            - Asia/Bangkok
                            - America/Los_Angeles
                            - America/New_York
                            - Europe/London
                        weekdays:
                          minItems: 1
                          maxItems: 7
                          type: array
                          items:
                            type: string
                            enum:
                              - sunday
                              - monday
                              - tuesday
                              - wednesday
                              - thursday
                              - friday
                              - saturday
                        start_time:
                          type: string
                          pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$
                        end_time:
                          type: string
                          pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$
                      required:
                        - time_zone
                        - weekdays
                        - start_time
                        - end_time
                      additionalProperties: false
                  additionalProperties: false
              required:
                - agent_id
              additionalProperties: false
          required:
            - kind
            - total_recipients
            - recipient_format
            - options
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              const: sms
            total_recipients:
              type: integer
              minimum: 1
              maximum: 100000
            upload_chunk_size:
              default: 1000
              type: integer
              minimum: 1
              maximum: 1000
            recipient_format:
              type: string
              const: recipients
            options:
              type: object
              properties:
                message:
                  type: string
                  minLength: 1
                  maxLength: 2000
                metadata:
                  type: object
                  propertyNames:
                    type: string
                    pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$
                  additionalProperties:
                    type: string
                    maxLength: 512
                reference_id:
                  type: string
                  minLength: 1
                  maxLength: 255
                external_id:
                  type: string
                  minLength: 1
                  maxLength: 255
                webhook:
                  type: object
                  properties:
                    url:
                      type: string
                      maxLength: 2048
                      format: uri
                    secret:
                      type: string
                      minLength: 32
                      maxLength: 256
                      pattern: ^[\x21-\x7e]+$
                  required:
                    - url
                    - secret
                  additionalProperties: false
                schedule:
                  type: object
                  properties:
                    start_at:
                      type: string
                      allOf:
                        - pattern: >-
                            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                        - pattern: >-
                            ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$
                    calling_window:
                      type: object
                      properties:
                        time_zone:
                          type: string
                          enum:
                            - Asia/Taipei
                            - Asia/Hong_Kong
                            - Asia/Shanghai
                            - Asia/Tokyo
                            - Asia/Seoul
                            - Asia/Singapore
                            - Asia/Bangkok
                            - America/Los_Angeles
                            - America/New_York
                            - Europe/London
                        weekdays:
                          minItems: 1
                          maxItems: 7
                          type: array
                          items:
                            type: string
                            enum:
                              - sunday
                              - monday
                              - tuesday
                              - wednesday
                              - thursday
                              - friday
                              - saturday
                        start_time:
                          type: string
                          pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$
                        end_time:
                          type: string
                          pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$
                      required:
                        - time_zone
                        - weekdays
                        - start_time
                        - end_time
                      additionalProperties: false
                  additionalProperties: false
                expires_at:
                  type: string
                  allOf:
                    - pattern: >-
                        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                    - pattern: >-
                        ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$
                test_mode:
                  type: boolean
              required:
                - message
              additionalProperties: false
          required:
            - kind
            - total_recipients
            - recipient_format
            - options
          additionalProperties: false
    BulkTask:
      type: object
      properties:
        id:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        kind:
          type: string
          enum:
            - calls
            - sms
        recipient_format:
          type: string
          enum:
            - contact_ids
            - recipients
        status:
          type: string
          enum:
            - uploading
            - queued
            - processing
            - completed
            - failed
        total_recipients:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        uploaded_recipients:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        submitted_recipients:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        settled_recipients:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        failed_recipients:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        unknown_recipients:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        total_parts:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        submitted_parts:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        failed_parts:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        error_code:
          anyOf:
            - type: string
            - type: 'null'
        upload_chunk_size:
          type: integer
          minimum: 1
          maximum: 1000
        created_at:
          type: string
      required:
        - id
        - kind
        - recipient_format
        - status
        - total_recipients
        - uploaded_recipients
        - submitted_recipients
        - settled_recipients
        - failed_recipients
        - unknown_recipients
        - total_parts
        - submitted_parts
        - failed_parts
        - error_code
        - upload_chunk_size
        - created_at
      additionalProperties: false
    ErrorEnvelope:
      type: object
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
        - error
    Error:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          enum:
            - authentication_required
            - invalid_api_key
            - api_key_expired
            - organization_not_enabled
            - insufficient_scope
            - unsupported_version
            - validation_error
            - invalid_json
            - resource_not_found
            - resource_state_conflict
            - method_not_allowed
            - request_too_large
            - unsupported_destination
            - contact_identity_conflict
            - idempotency_key_required
            - idempotency_conflict
            - idempotency_in_progress
            - duplicate_active_run
            - rate_limit_exceeded
            - recipient_blocked_by_policy
            - internal_error
          example: validation_error
        message:
          type: string
          example: The request could not be validated.
        request_id:
          type: string
          pattern: ^[A-Za-z0-9._:-]{1,64}$
          example: req_demo_001
        details:
          $ref: '#/components/schemas/ErrorDetails'
      required:
        - code
        - message
        - request_id
    ErrorDetails:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
          description: >-
            LINE resource conflict reason. No send was claimed; correct the
            binding or channel before retrying.
          enum:
            - line_multiple_accounts
            - line_not_following
            - line_not_linked
            - line_recipient_invalid
            - line_channel_missing
        fields:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/ErrorField'
        truncated:
          type: boolean
          const: true
        supported_versions:
          type: array
          items:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
        existing_run_id:
          type: string
          minLength: 1
          maxLength: 255
          description: An opaque resource identifier.
          example: run_demo_001
    ErrorField:
      type: object
      additionalProperties: false
      properties:
        path:
          type: string
          example: recipient.phone_number
        code:
          type: string
          example: invalid_e164
      required:
        - path
        - code
  headers:
    Brightalk-Version:
      description: The date-based version applied to the request.
      required: true
      schema:
        type: string
        const: '2026-07-16'
    X-Request-Id:
      description: The accepted caller correlation value or a server-generated replacement.
      required: true
      schema:
        type: string
        pattern: ^[A-Za-z0-9._:-]{1,64}$
    RateLimit-Limit:
      description: The effective request allowance for the selected bucket.
      schema:
        type: integer
        minimum: 1
    RateLimit-Remaining:
      description: The nonnegative number of requests remaining in the selected bucket.
      schema:
        type: integer
        minimum: 0
    RateLimit-Reset:
      description: >-
        A nonnegative integer number of delta-seconds from response generation
        until the effective bucket resets; never an epoch timestamp.
      schema:
        type: integer
        minimum: 0
    Idempotency-Replayed:
      description: >-
        Present only when a completed idempotent result is replayed. Its literal
        boolean-string value is true.
      schema:
        type: string
        const: 'true'
      example: 'true'
    Allow:
      description: A comma-separated list of methods allowed on the known path.
      schema:
        type: string
        example: GET, POST
    Retry-After:
      description: >-
        A nonnegative integer number of delta-seconds to wait before retrying;
        never an epoch timestamp.
      schema:
        type: integer
        minimum: 0
  responses:
    BadRequest:
      description: >-
        The version, request, query, or state-independent destination validation
        failed.
      headers:
        Brightalk-Version:
          $ref: '#/components/headers/Brightalk-Version'
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            validationError:
              value:
                error:
                  code: validation_error
                  message: The request could not be validated.
                  request_id: req_demo_001
                  details:
                    fields:
                      - path: recipient.phone_number
                        code: invalid_e164
            unsupportedVersion:
              value:
                error:
                  code: unsupported_version
                  message: The requested API version is not supported.
                  request_id: req_demo_001
                  details:
                    supported_versions:
                      - '2026-07-16'
            unsupportedDestination:
              value:
                error:
                  code: unsupported_destination
                  message: The destination is not supported.
                  request_id: req_demo_001
    Unauthorized:
      description: Authentication failed.
      headers:
        Brightalk-Version:
          $ref: '#/components/headers/Brightalk-Version'
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            missingBearer:
              value:
                error:
                  code: authentication_required
                  message: Authentication is required.
                  request_id: req_demo_001
            malformedBearer:
              value:
                error:
                  code: authentication_required
                  message: Authentication is required.
                  request_id: req_demo_001
            unknownOrRevokedCredential:
              value:
                error:
                  code: invalid_api_key
                  message: The API key is invalid.
                  request_id: req_demo_001
            expiredCredential:
              value:
                error:
                  code: api_key_expired
                  message: The API key has expired.
                  request_id: req_demo_001
    Forbidden:
      description: The request is not authorized for this API operation.
      headers:
        Brightalk-Version:
          $ref: '#/components/headers/Brightalk-Version'
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            organizationNotEnabled:
              value:
                error:
                  code: organization_not_enabled
                  message: The organization is not enabled for the Public API.
                  request_id: req_demo_001
            insufficientScope:
              value:
                error:
                  code: insufficient_scope
                  message: The API key does not have the required scope.
                  request_id: req_demo_001
    NotFound:
      description: The resource is absent or not visible to this organization.
      headers:
        Brightalk-Version:
          $ref: '#/components/headers/Brightalk-Version'
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            resourceNotFound:
              value:
                error:
                  code: resource_not_found
                  message: The requested resource was not found.
                  request_id: req_demo_001
    MethodNotAllowed:
      description: The path is known but the method is not allowed.
      headers:
        Brightalk-Version:
          $ref: '#/components/headers/Brightalk-Version'
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Allow:
          $ref: '#/components/headers/Allow'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            methodNotAllowed:
              value:
                error:
                  code: method_not_allowed
                  message: The method is not allowed for this resource.
                  request_id: req_demo_001
    Conflict:
      description: >-
        The resource state, identity, or idempotency claim conflicts with the
        request.
      headers:
        Brightalk-Version:
          $ref: '#/components/headers/Brightalk-Version'
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            stateConflict:
              value:
                error:
                  code: resource_state_conflict
                  message: The resource is not in a compatible state.
                  request_id: req_demo_001
            identityConflict:
              value:
                error:
                  code: contact_identity_conflict
                  message: The contact identity conflicts with an existing contact.
                  request_id: req_demo_001
            idempotencyConflict:
              value:
                error:
                  code: idempotency_conflict
                  message: >-
                    The idempotency key was already used for a different
                    request.
                  request_id: req_demo_001
            idempotencyInProgress:
              value:
                error:
                  code: idempotency_in_progress
                  message: A request with this idempotency key is still in progress.
                  request_id: req_demo_001
            duplicateActiveRun:
              value:
                error:
                  code: duplicate_active_run
                  message: An active run already exists for this contact.
                  request_id: req_demo_001
                  details:
                    existing_run_id: run_demo_001
    RequestTooLarge:
      description: The raw JSON request body exceeds 1 MiB.
      headers:
        Brightalk-Version:
          $ref: '#/components/headers/Brightalk-Version'
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            requestTooLarge:
              value:
                error:
                  code: request_too_large
                  message: The request body is too large.
                  request_id: req_demo_001
    TooManyRequests:
      description: The selected request bucket is exhausted.
      headers:
        Brightalk-Version:
          $ref: '#/components/headers/Brightalk-Version'
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            rateLimitExceeded:
              value:
                error:
                  code: rate_limit_exceeded
                  message: The rate limit has been exceeded.
                  request_id: req_demo_001
    InternalError:
      description: The request could not be completed safely.
      headers:
        Brightalk-Version:
          $ref: '#/components/headers/Brightalk-Version'
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            internalError:
              value:
                error:
                  code: internal_error
                  message: An unexpected error occurred.
                  request_id: req_demo_001
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Brightalk API key
      description: Use a server-side Brightalk API key in the Authorization header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.