openapi: 3.0.0
info:
  title: Salesforce Flow Automation Flows API
  description: The Salesforce Flow Automation API provides programmatic access to Salesforce Flow definitions, interviews (running flow instances), and flow runtime execution. Flows are the primary automation tool in Salesforce, replacing Workflow Rules and Process Builder for automating business processes.
  version: '59.0'
  contact:
    name: Salesforce Developer Relations
    url: https://developer.salesforce.com
  license:
    name: Salesforce API Terms
    url: https://www.salesforce.com/company/legal/agreements/
servers:
- url: https://{instance}.salesforce.com/services/data/v59.0
  description: Salesforce REST API server (replace {instance} with your org domain).
  variables:
    instance:
      default: yourInstance
      description: Your Salesforce org instance (e.g., na1, eu6, or MyDomain).
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Flows
  description: Manage Salesforce Flow definitions and metadata.
paths:
  /tooling/query:
    get:
      operationId: queryFlowDefinitions
      tags:
      - Flows
      summary: Query Flow Definitions
      description: Query Salesforce Flow definitions using SOQL via the Tooling API. Returns flow metadata including API name, label, version, and status.
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: SOQL query (e.g. SELECT Id, ApiName, Label, Status FROM FlowDefinition)
        example: SELECT Id, ApiName, Label, Status, ActiveVersionId FROM FlowDefinition LIMIT 50
      responses:
        '200':
          description: SOQL query results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoqlQueryResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /tooling/sobjects/Flow/{id}:
    get:
      operationId: getFlowVersion
      tags:
      - Flows
      summary: Get Flow Version
      description: Retrieve a specific Flow version record from the Tooling API including full metadata for a flow definition.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The Salesforce Flow record ID.
        example: 301xx000000002ZAAQ
      responses:
        '200':
          description: Flow version record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /actions/custom/flow/{flowApiName}:
    post:
      operationId: invokeFlow
      tags:
      - Flows
      summary: Invoke Flow via REST Action
      description: Invoke an autolaunched Salesforce Flow as a REST action. Passes input variables to the flow and returns output variables.
      parameters:
      - name: flowApiName
        in: path
        required: true
        schema:
          type: string
        description: The API name of the flow to invoke.
        example: My_Order_Fulfillment_Flow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowInvocationRequest'
      responses:
        '200':
          description: Flow invocation result with output variables.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowInvocationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    FlowInvocationRequest:
      type: object
      description: Request body for invoking a flow via REST action.
      properties:
        inputs:
          type: array
          description: Array of input variable objects to pass to the flow.
          items:
            type: object
            additionalProperties: true
          example:
          - recordId: 001xx000003GYn1AAG
            action: Approve
    SoqlQueryResult:
      type: object
      description: SOQL query result.
      properties:
        totalSize:
          type: integer
          description: Total number of records matching the query.
        done:
          type: boolean
          description: True if all records returned.
        nextRecordsUrl:
          type: string
          description: URL to retrieve next page of results.
        records:
          type: array
          description: Array of records.
          items:
            type: object
            additionalProperties: true
    FlowInvocationResponse:
      type: object
      description: Response from a flow REST action invocation.
      properties:
        actionName:
          type: string
          description: The name of the invoked flow action.
        isSuccess:
          type: boolean
          description: Whether the flow invocation succeeded.
        outputValues:
          type: object
          description: Output variable values from the flow.
          additionalProperties: true
        errors:
          type: array
          description: Errors if the flow failed.
          items:
            type: object
    FlowVersion:
      type: object
      description: A Salesforce Flow version with metadata.
      properties:
        Id:
          type: string
          description: Record ID.
        ApiName:
          type: string
          description: Developer API name of the flow.
        Label:
          type: string
          description: Human-readable label.
        Status:
          type: string
          enum:
          - Active
          - Draft
          - Obsolete
          - InvalidDraft
          description: Flow version status.
        ProcessType:
          type: string
          description: Flow type (Flow, AutoLaunchedFlow, etc.).
        TriggerType:
          type: string
          description: What triggers the flow (RecordBeforeSave, RecordAfterSave, etc.).
  responses:
    Unauthorized:
      description: Unauthorized - invalid or expired credentials.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                message:
                  type: string
                errorCode:
                  type: string
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                message:
                  type: string
                errorCode:
                  type: string
    NotFound:
      description: Record not found.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                message:
                  type: string
                errorCode:
                  type: string
    Forbidden:
      description: Forbidden - insufficient permissions.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                message:
                  type: string
                errorCode:
                  type: string
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.salesforce.com/services/oauth2/authorize
          tokenUrl: https://login.salesforce.com/services/oauth2/token
          scopes:
            api: Access and manage your data
            refresh_token: Perform requests at any time
        clientCredentials:
          tokenUrl: https://login.salesforce.com/services/oauth2/token
          scopes:
            api: Access and manage your data
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT