openapi: 3.0.4
info:
  title: Flow API
  description: |-
    Welcome the Voxtelesys Flow API. This API offers a solution for creating Flow executions programmatically.
  version: v1
servers:
  - url: https://flowapi.voxtelesys.net/api/v1
paths:
  /flows/{flow_guid}/variables:
    get:
      tags:
        - Flows
      security:
        - OAuth2: ['flowapi:flows:view']
      summary: Get Flow Variables
      description: Endpoint for getting the variables of a flow. Only flow parameters and global variables are returned.
      parameters:
        - name: flow_guid
          in: path
          example: 639a6020-b5d3-47be-9413-6cc3fe54b161
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowVariables"
  /flows/{flow_guid}/executions:
    post:
      tags:
        - Flows
      security:
        - OAuth2: ['flowapi:flows:manage']
      summary: Create a Flow Execution
      description: Endpoint for creating a new Flow Execution.
      requestBody:
        content:
          application/json:
            schema:
              required:
                - to
                - from
              type: object
              properties:
                to:
                  type: string
                  description: The E164-formatted phone number or email address to use as the destination address for the execution.
                  example: "13003003000"
                from:
                  type: string
                  description: The E164-formatted phone number or the username of an email address to use as the originating address for the execution.
                  example: "13003003000"
                parameters:
                  type: object
                  description: 	An object with any additional parameters to be passed into the execution.
                  example: { "foo": "bar"}
                tag:
                  type: string
                  description: String which will be included in callback events (max 256 chars), typically used to store an external identifier for the execution. Tags are propagated to voice, sms, and email channels called during the execution.
                  example: "261f6924-6982-11ea-bc55-0242ac130003"
                bulk_tag:
                  type: string
                  description: Used for bulk flow executions, allows grouping of executions. Tags are propagated to voice, sms, and email channels called during the execution.
                  example: "4de1d075-2a7e-404e-abac-3f80560db42f"
                status_callback:
                  $ref: "#/components/schemas/ClientCallback"
                  description: The absolute URL to send callbacks to when updates/actions occur during the execution.
      parameters:
        - name: flow_guid
          in: path
          example: 6b40db14-05aa-4266-b006-8b13a6639eb7
          schema:
            type: string
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://authapi.voxtelesys.net/api/v1/oauth/token
          scopes:
            flowapi:flows:manage: Ability to create new flow executions
            flowapi:flows:view: Ability to view flow variables
  schemas:
    FlowVariables:
      type: object
      properties:
        parameters:
          type: array
          example: ["foo","bar"]
          description: The variables of the flow. Only global variables and flow parameters are returned.
    ClientCallback:
      type: object
      required:
        - url
        - method
      properties:
        url:
          type: string
          description: The callback URL.
          example: "https://example.com/callback"
        method:
          type: string
          enum:
            - GET
            - POST
          description: HTTP method to use for the callback.
          example: POST
