> ## 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.

# Start an active Automation

> Queues one active dashboard-managed Automation for one contact. The Automation owns its agent, waits, retry rules, and branching. An Idempotency-Key is required; the sanitized raw JSON body is limited to 1 MiB. Every response includes Brightalk-Version and X-Request-Id; rate-limited responses also expose the effective bucket counters.



## OpenAPI

````yaml /openapi/openapi.yaml post /automation-runs
openapi: 3.1.0
info:
  title: Brightalk Public API
  version: '2026-07-16'
  description: >-
    Private-beta server-to-server REST API for AI calls, batch dialing, and
    dashboard-managed Automation runs.
  license:
    name: Brightalk Private Beta Terms
    identifier: LicenseRef-Brightalk-Private-Beta
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: Start and control one-contact Automation runs.
paths:
  /automation-runs:
    post:
      tags:
        - Automation runs
      summary: Start an active Automation
      description: >-
        Queues one active dashboard-managed Automation for one contact. The
        Automation owns its agent, waits, retry rules, and branching. An
        Idempotency-Key is required; the sanitized raw JSON body is limited to 1
        MiB. Every response includes Brightalk-Version and X-Request-Id;
        rate-limited responses also expose the effective bucket counters.
      operationId: createAutomationRun
      parameters:
        - $ref: '#/components/parameters/BrightalkVersion'
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        required: true
        description: >-
          JSON request body. The raw encoded body is limited to 1 MiB and
          unknown fields are rejected.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAutomationRunRequest'
      responses:
        '202':
          description: Automation run accepted into the durable queue.
          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/AutomationRun'
        '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/automation-runs' \
              --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
              --header "Brightalk-Version: 2026-07-16" \
              --header "Content-Type: application/json" \
              --header "Idempotency-Key: createAutomationRun-example-001" \
              --data '{"automation_id":"atm_demo_001","contact_id":"con_demo_001"}'
        - lang: javascript
          label: JavaScript
          source: >-
            const response = await
            fetch("https://api.brightalk.ai/automation-runs", {
              method: "POST",
              headers: {
                Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
                "Brightalk-Version": "2026-07-16",
                "Content-Type": "application/json",
                "Idempotency-Key": "createAutomationRun-example-001",
              },
              body: JSON.stringify({"automation_id":"atm_demo_001","contact_id":"con_demo_001"}),
            });

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

            response = requests.request(
                "POST",
                "https://api.brightalk.ai/automation-runs",
                headers={
                "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
                "Brightalk-Version": "2026-07-16",
                "Content-Type": "application/json",
                "Idempotency-Key": "createAutomationRun-example-001",
                },
                json={"automation_id":"atm_demo_001","contact_id":"con_demo_001"},
            )
            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 private-beta 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:
    CreateAutomationRunRequest:
      oneOf:
        - type: object
          additionalProperties: false
          properties:
            automation_id:
              type: string
              minLength: 1
              maxLength: 255
              description: An opaque resource identifier.
              example: atm_demo_001
            contact_id:
              type: string
              minLength: 1
              maxLength: 255
              description: An opaque resource identifier.
              example: con_demo_001
            input:
              $ref: '#/components/schemas/AutomationInput'
          required:
            - automation_id
            - contact_id
        - type: object
          additionalProperties: false
          properties:
            automation_id:
              type: string
              minLength: 1
              maxLength: 255
              description: An opaque resource identifier.
              example: atm_demo_001
            recipient:
              $ref: '#/components/schemas/InlineRecipient'
            input:
              $ref: '#/components/schemas/AutomationInput'
          required:
            - automation_id
            - recipient
    AutomationRun:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 255
          description: An opaque resource identifier.
          example: run_demo_001
        status:
          $ref: '#/components/schemas/AutomationRunStatus'
        automation_id:
          type: string
          minLength: 1
          maxLength: 255
          description: An opaque resource identifier.
          example: atm_demo_001
        contact_id:
          type: string
          minLength: 1
          maxLength: 255
          description: An opaque resource identifier.
          example: con_demo_001
        input:
          $ref: '#/components/schemas/AutomationInput'
        failure_code:
          type: string
          description: A stable failure classification when the run fails.
          example: step_failed
        queued_at:
          type: string
          format: date-time
          description: When the run entered the durable queue.
          example: '2026-07-20T01:00:00Z'
        started_at:
          type: string
          format: date-time
          description: When execution began.
          example: '2026-07-20T01:00:00Z'
        completed_at:
          type: string
          format: date-time
          description: When execution completed.
          example: '2026-07-20T01:00:00Z'
        cancelled_at:
          type: string
          format: date-time
          description: When cancellation completed.
          example: '2026-07-20T01:00:00Z'
        created_at:
          type: string
          format: date-time
          description: When the run resource was created.
          example: '2026-07-20T01:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the run resource was last updated.
          example: '2026-07-20T01:00:00Z'
      required:
        - id
        - status
        - automation_id
        - contact_id
        - input
        - queued_at
        - created_at
        - updated_at
    AutomationInput:
      type: object
      additionalProperties: false
      maxProperties: 0
      properties: {}
      description: >-
        Only names declared by the selected Automation may be supplied. Input is
        limited to 32 KiB of serialized JSON and nesting depth 10. The current
        contract exposes no declared names, so omit input or send an empty
        object.
    InlineRecipient:
      type: object
      additionalProperties: false
      properties:
        external_id:
          type: string
          pattern: ^\s*\S(?:[\s\S]{0,253}\S)?\s*$
          description: >-
            Leading and trailing whitespace is trimmed; the remaining value must
            contain 1–255 characters.
          example: customer-8421
        source:
          type: string
          pattern: ^[a-z][a-z0-9_-]{0,63}$
          default: public_api
          description: An allowlisted identity namespace. Omit to use public_api.
          example: public_api
        name:
          type: string
          pattern: ^\s*\S(?:[\s\S]{0,253}\S)?\s*$
          description: >-
            Leading and trailing whitespace is trimmed; the remaining value must
            contain 1–255 characters.
          example: Example Customer
        phone_number:
          type: string
          pattern: ^\+[1-9]\d{7,14}$
          description: A strict E.164 phone number.
          example: '+12025550123'
        email:
          type:
            - string
            - 'null'
          format: email
          maxLength: 320
          example: customer@example.com
        company:
          type:
            - string
            - 'null'
          pattern: ^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$
          description: >-
            Leading and trailing whitespace is trimmed; the remaining value may
            contain at most 255 characters.
          example: Example Co.
        role:
          type:
            - string
            - 'null'
          pattern: ^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$
          description: >-
            Leading and trailing whitespace is trimmed; the remaining value may
            contain at most 255 characters.
          example: Operations Manager
        city:
          type:
            - string
            - 'null'
          pattern: ^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$
          description: >-
            Leading and trailing whitespace is trimmed; the remaining value may
            contain at most 255 characters.
          example: Taipei
        country:
          type:
            - string
            - 'null'
          pattern: ^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$
          description: >-
            Leading and trailing whitespace is trimmed; the remaining value may
            contain at most 255 characters.
          example: TW
      required:
        - external_id
        - name
        - phone_number
    AutomationRunStatus:
      type: string
      enum:
        - queued
        - running
        - waiting
        - completed
        - failed
        - cancelled
    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
            - 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:
        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 organization is not enabled or the credential lacks a required
        scope.
      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 private-beta server credential in the Authorization header.

````