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

# Run an existing pipeline

> Execute the latest ready revision of an existing reusable pipeline. Use this endpoint for each new execution instead of creating another pipeline.

Before running, fetch GET /v1/workspaces/{workspaceId}/pipelines/{pipelineId} if you need the run inputJsonSchema. The request body must wrap playbook-specific data under input.

Scheduling example, run many times:

{
  "input": {
    "dateRange": {
      "start": "2026-05-11",
      "end": "2026-05-17"
    }
  }
}

For scheduling pipelines, reusable rules stay in pipeline instructions. A run only supplies the dateRange for this execution.



## OpenAPI

````yaml /openapi.json post /v1/workspaces/{workspaceId}/pipelines/{pipelineId}/runs
openapi: 3.1.0
info:
  title: Erna API
  version: 1.0.0
  description: >-
    AI business operations platform API.


    Erna uses a reusable pipeline lifecycle: Playbook -> Pipeline -> Revision ->
    Run.


    - A playbook defines the repeatable task type, generation behavior, and run
    input/output contract.

    - A pipeline stores reusable instructions and configuration for one
    playbook. Do not create a new pipeline for every execution.

    - A revision is the built executable version of a pipeline definition.

    - A run executes the latest ready revision with playbook-specific input.


    For scheduling, create one pipeline with the reusable business rules, staff
    context, and constraints. Then run that pipeline repeatedly with
    date-specific input such as { "input": { "dateRange": { "start":
    "2026-05-11", "end": "2026-05-17" } } }.
servers:
  - url: https://api.erna.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/workspaces/{workspaceId}/pipelines/{pipelineId}/runs:
    post:
      tags:
        - Runs
      summary: Run an existing pipeline
      description: >-
        Execute the latest ready revision of an existing reusable pipeline. Use
        this endpoint for each new execution instead of creating another
        pipeline.


        Before running, fetch GET
        /v1/workspaces/{workspaceId}/pipelines/{pipelineId} if you need the run
        inputJsonSchema. The request body must wrap playbook-specific data under
        input.


        Scheduling example, run many times:


        {
          "input": {
            "dateRange": {
              "start": "2026-05-11",
              "end": "2026-05-17"
            }
          }
        }


        For scheduling pipelines, reusable rules stay in pipeline instructions.
        A run only supplies the dateRange for this execution.
      operationId: createPipelineRun
      parameters:
        - schema:
            type: string
          required: true
          name: workspaceId
          in: path
        - schema:
            type: string
          required: true
          name: pipelineId
          in: path
        - schema:
            type: string
            minLength: 1
            example: unique-idempotency-key
          required: true
          name: Idempotency-Key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartPipelineRunV1Request'
      responses:
        '200':
          description: Run returned in its current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartPipelineRunV1AcceptedResponse'
        '202':
          description: Run accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  runId:
                    type: string
                  playbookId:
                    type: string
                    enum:
                      - scheduling
                      - reporting
                  pipelineId:
                    type: string
                  revisionId:
                    type: string
                  status:
                    type: string
                    enum:
                      - running
                      - complete
                      - failed
                  output: {}
                  error: {}
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                    required:
                      - self
                    additionalProperties: false
                required:
                  - runId
                  - playbookId
                  - pipelineId
                  - revisionId
                  - status
                  - createdAt
                  - updatedAt
                  - links
                additionalProperties: false
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsResponse'
        '409':
          description: Pipeline not ready
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - pipeline_not_ready
                  message:
                    type: string
                  pipelineStatus:
                    type: string
                    enum:
                      - building
                      - ready
                      - failed
                required:
                  - error
                  - message
                  - pipelineStatus
                additionalProperties: false
        '422':
          description: Invalid run input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRunInputResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    StartPipelineRunV1Request:
      type: object
      properties:
        input:
          type: object
          properties: {}
          default: {}
          additionalProperties: {}
          description: >-
            Playbook-specific input for this one execution. For scheduling, the
            run input is only the date range to schedule.
      additionalProperties: false
    StartPipelineRunV1AcceptedResponse:
      type: object
      properties:
        runId:
          type: string
        playbookId:
          type: string
          enum:
            - scheduling
            - reporting
        pipelineId:
          type: string
        revisionId:
          type: string
        status:
          type: string
          enum:
            - running
            - complete
            - failed
        output: {}
        error: {}
        createdAt:
          type: string
        updatedAt:
          type: string
        links:
          type: object
          properties:
            self:
              type: string
          required:
            - self
          additionalProperties: false
      required:
        - runId
        - playbookId
        - pipelineId
        - revisionId
        - status
        - createdAt
        - updatedAt
        - links
      additionalProperties: false
    InsufficientCreditsResponse:
      type: object
      properties:
        error:
          type: string
          enum:
            - insufficient_credits
        message:
          type: string
        billing:
          type: object
          properties:
            checkoutPath:
              type: string
          required:
            - checkoutPath
      required:
        - error
        - message
        - billing
      additionalProperties: false
    InvalidRunInputResponse:
      type: object
      properties:
        error:
          type: string
          enum:
            - invalid_run_input
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
            required:
              - path
              - message
      required:
        - error
        - message
        - details
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth2 access token or API key

````