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

# Trigger automation from GitHub



## OpenAPI

````yaml /openapi/customer-api.json post /ai/trigger/github
openapi: 3.0.0
info:
  contact: {}
  description: >-
    Flow customer API reference. Start with the [quickstart](/api/quickstart)
    and [authentication guide](/api/authentication).
  title: Customer API
  version: 1.0.0
servers:
  - description: Flow API
    url: https://backend.branch.flowengineering.com
security: []
tags:
  - name: Automations
  - name: Branches
  - name: Comments
  - name: Convert
  - name: Data Model
  - name: Diagrams
  - name: Entities
  - name: Files
  - name: Import
  - name: Notifications
  - name: Projects
  - name: ReqIF
  - name: ReqIF Import
  - name: Shared Access Grants
  - name: User Groups
  - name: Users
paths:
  /ai/trigger/github:
    post:
      tags:
        - Automations
      summary: Trigger automation from GitHub
      operationId: AutomationTriggerController_triggerGitHub
      parameters:
        - description: Workspace identifier
          in: header
          name: customer
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerGitHubDto'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerResponseDto'
          description: ''
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerResponseDto'
          description: >-
            The matched automations were started, not awaited. Each result
            carries its run id and `status: "running"`; read the outcome from
            GET /ai/trigger/runs. A request sending `wait: true` instead
            responds once every run has finished, with the outcomes inline.
      security:
        - api-key: []
        - bearer: []
components:
  schemas:
    TriggerGitHubDto:
      properties:
        action:
          type: string
        base_branch:
          type: string
        body:
          type: string
        diff:
          type: string
        head_branch:
          type: string
        pr_number:
          type: number
        project_id:
          type: string
        repo:
          type: string
        title:
          type: string
        wait:
          default: false
          description: >-
            Whether to hold the request open until every matched automation has
            finished running. Defaults to false: the runs start, the response is
            202 with one run id each, and you read results from GET
            /ai/trigger/runs. Pass true only when the caller genuinely cannot
            poll — it makes response time the sum of the runs, an agent run has
            no time bound, and the request dies on the shortest timeout between
            you and this API (our load balancer cuts an idle connection at 60s),
            which loses the response while the runs themselves carry on.
          type: boolean
      required:
        - repo
        - pr_number
        - title
        - action
        - diff
      type: object
    TriggerResponseDto:
      properties:
        results:
          items:
            $ref: '#/components/schemas/TriggerResultItemDto'
          type: array
      required:
        - results
      type: object
    TriggerResultItemDto:
      properties:
        agent_id:
          type: string
        automation_id:
          type: string
        automation_name:
          type: string
        branches:
          default: []
          items:
            type: object
          type: array
        error:
          nullable: true
          type: string
        integration_grade:
          nullable: true
          type: string
        integration_response:
          nullable: true
          type: string
        project_id:
          type: string
        project_slug:
          nullable: true
          type: string
        status:
          enum:
            - running
            - completed
            - failed
          type: string
      required:
        - agent_id
        - status
        - automation_id
        - automation_name
        - integration_response
        - integration_grade
        - branches
        - project_slug
        - project_id
        - error
      type: object
  securitySchemes:
    api-key:
      in: header
      name: X-API-Key
      type: apiKey
    bearer:
      bearerFormat: JWT
      scheme: bearer
      type: http

````