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

# Create Workflow Campaign API

> Create a campaign that pins one published version of a workflow. Pass version null to pin the latest published version.

<Note>
  The version pin is resolved at creation time and is immutable afterwards — publishing a newer version later never changes what this campaign runs.
</Note>


## OpenAPI

````yaml POST /workflow-campaigns
openapi: 3.1.0
info:
  title: Bolna API
  description: >-
    Use and leverage Bolna Voice AI using APIs through HTTP requests from any
    language in your applications and workflows.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.bolna.ai
    description: Production server
security:
  - bearerAuth: []
paths:
  /workflow-campaigns:
    post:
      description: >-
        Creates a campaign in `draft` status. A campaign pins one published
        version of one workflow at creation time — `version` `null` pins the
        latest published version — and the pin is immutable afterwards.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowCampaignCreateRequest'
        required: true
      responses:
        '201':
          description: Campaign created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowCampaign'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowError'
        '422':
          description: >-
            `no_published_version` — the workflow has no published version to
            pin, or `validation_failed`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowError'
components:
  schemas:
    WorkflowCampaignCreateRequest:
      type: object
      required:
        - workflow_id
        - name
      properties:
        workflow_id:
          type: string
          format: uuid
          description: The workflow to run.
        version:
          type: integer
          nullable: true
          description: >-
            Published version to pin. `null` pins the latest published version
            at creation time. The pin is immutable after create.
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: Campaign display name.
          example: August loan follow-ups
        binding:
          type: object
          description: >-
            Optional per-campaign overrides. `agent_overrides` maps agent node
            ids to replacement agent ids; `number_overrides` maps agent node ids
            to originating phone numbers.
        scheduled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Timezone-aware timestamp to start the campaign at. Omit to start
            manually.
    WorkflowCampaign:
      type: object
      required:
        - id
        - name
        - workflow_id
        - workflow_version
        - kind
        - status
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        workflow_id:
          type: string
          format: uuid
        workflow_version:
          type: integer
          description: The pinned published version.
        kind:
          type: string
          enum:
            - batch
            - continuous
            - api
          description: >-
            `batch` holds uploaded entries; `api` is the implicit campaign
            behind single runs.
        status:
          type: string
          enum:
            - draft
            - scheduled
            - running
            - paused
            - completed
            - aborted
          description: >-
            Lifecycle is `draft` → `scheduled` → `running` → (`paused` ↔
            `running`) → `completed` or `aborted`.
        scheduled_at:
          type: string
          format: date-time
          nullable: true
        entries_count:
          type: integer
        success_count:
          type: integer
        failure_count:
          type: integer
        neutral_count:
          type: integer
        terminal_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    WorkflowError:
      type: object
      description: >-
        Error envelope returned by every workflow endpoint. `detail.code` is a
        stable machine-readable code; extra keys (such as `current_revision` on
        `revision_conflict`, `execution_id` on `duplicate_run`, or `issues` on
        `invalid_definition`) ride alongside it.
      required:
        - detail
      properties:
        detail:
          type: object
          additionalProperties: true
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code.
              example: revision_conflict
            message:
              type: string
              description: Human-readable explanation.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````