Box Workflows API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Workflows API
  description: Needs a description.
tags:
- name: Workflows
  description: 'Box Relay Workflows are objects that represent

    a named collection of flows.'
  x-box-tag: workflows
paths:
  /workflows:
    get:
      operationId: get_workflows
      summary: Box List workflows
      tags:
      - Workflows
      x-box-tag: workflows
      description: 'Returns list of workflows that act on a given `folder ID`, and

        have a flow with a trigger type of `WORKFLOW_MANUAL_START`.


        You application must be authorized to use the `Manage Box Relay` application

        scope within the developer console in to use this endpoint.'
      parameters:
      - name: folder_id
        description: 'The unique identifier that represent a folder.


          The ID for any folder can be determined

          by visiting this folder in the web application

          and copying the ID from the URL. For example,

          for the URL `https://*.app.box.com/folder/123`

          the `folder_id` is `123`.


          The root folder of a Box account is

          always represented by the ID `0`.'
        example: '12345'
        in: query
        required: true
        schema:
          type: string
          nullable: false
      - name: trigger_type
        description: Type of trigger to search for.
        example: WORKFLOW_MANUAL_START
        in: query
        required: false
        schema:
          type: string
          nullable: false
      - name: limit
        description: The maximum number of items to return per page.
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          maximum: 1000
      - name: marker
        description: 'Defines the position marker at which to begin returning results. This is

          used when paginating using marker-based pagination.


          This requires `usemarker` to be set to `true`.'
        in: query
        required: false
        example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
        schema:
          type: string
      responses:
        '200':
          description: Returns the workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflows'
        '400':
          description: Returned if the trigger type is not `WORKFLOW_MANUAL_START`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned if the folder is not found, or the user does not

            have access to the folder.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /workflows/{workflow_id}/start:
    post:
      operationId: post_workflows_id_start
      summary: Box Starts workflow based on request body
      tags:
      - Workflows
      x-box-tag: workflows
      description: 'Initiates a flow with a trigger type of `WORKFLOW_MANUAL_START`.


        You application must be authorized to use the `Manage Box Relay` application

        scope within the developer console.'
      parameters:
      - name: workflow_id
        description: The ID of the workflow.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - flow
              - files
              - folder
              properties:
                type:
                  type: string
                  description: The type of the parameters object
                  example: workflow_parameters
                  enum:
                  - workflow_parameters
                flow:
                  type: object
                  description: The flow that will be triggered
                  properties:
                    type:
                      type: string
                      description: The type of the flow object
                      example: flow
                    id:
                      type: string
                      description: The id of the flow
                      example: '123456789'
                files:
                  type: array
                  description: 'The array of files for which the workflow should start. All files

                    must be in the workflow''s configured folder.'
                  items:
                    type: object
                    description: A file the workflow should start for
                    properties:
                      type:
                        type: string
                        description: The type of the file object
                        example: file
                        enum:
                        - file
                      id:
                        type: string
                        description: The id of the file
                        example: '12345678'
                folder:
                  type: object
                  description: The folder object for which the workflow is configured.
                  properties:
                    type:
                      type: string
                      description: The type of the folder object
                      example: folder
                      enum:
                      - folder
                    id:
                      type: string
                      description: The id of the folder
                      example: '87654321'
                outcomes:
                  type: array
                  description: A list of outcomes required to be configured at start time.
                  items:
                    type: object
                    description: 'A configurable outcome the workflow should complete. If you

                      have a `task_completion_rule`, you may input `all_assignees` or

                      `any_assignee` in the `variable_value` field. Similarly, if you

                      have a `collaborator_role`, you may input `editor`, `viewer`,

                      `previewer`, `uploader`, `previewer uploader`, `viewer uploader`

                      , `co-owner` in the `variable_value` field.'
                    properties:
                      id:
                        type: string
                        description: The id of the outcome
                        example: '890375782'
                      type:
                        type: string
                        description: The type of the outcome object
                        example: outcome
                        enum:
                        - outcome
                      parameter:
                        type: string
                        description: 'This is a placeholder example for various objects that

                          can be passed in - refer to the guides section to find

                          out more information.'
                        example: placeholder
      responses:
        '204':
          description: Starts the workflow.
        '400':
          description: "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `workflow_is_not_enabled` when the workflow is not enabled\n* `workflow_not_active_on_provided_folder` when the workflow is not\n  enabled for the specified folder id\n* `parameters_provided_do_not_match_target_outcome` when the provided\n  parameters do not match the expected parameters"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: "Returns an error if there are insufficient permissions.\n\n* `insufficient_access` when the user does not have access rights to file\n  or folder\n* `missing_relay_full_access` when the user does not have access to Relay\n  Full"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returns an error if the workflow could not be found,

            or the authenticated user does not have access to the workflow.


            * `workflow_not_found` when the workflow is not found

            * `flow_missing_or_inaccessible` when the flow is not a manual start flow'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    User--Base:
      title: User (Base)
      type: object
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'A mini representation of a user, used when

        nested within another resource.'
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: The unique identifier for this user
          example: '11446498'
        type:
          type: string
          description: '`user`'
          example: user
          nullable: false
          enum:
          - user
    Workflow--Mini:
      title: Workflow (Mini)
      type: object
      x-box-resource-id: workflow--mini
      x-box-tag: workflows
      x-box-variants:
      - mini
      - standard
      - full
      x-box-variant: mini
      description: 'Box Relay Workflows are objects that represent a named collection of flows.


        You application must be authorized to use the `Manage Box Relay` application

        scope within the developer console in order to use this resource.'
      properties:
        id:
          type: string
          description: The unique identifier for the workflow
          example: '11446498'
        type:
          type: string
          description: '`workflow`'
          example: workflow
          enum:
          - workflow
        name:
          type: string
          example: New Hire Workflow
          description: The name of the workflow
        description:
          type: string
          description: The description for a workflow.
          example: This workflow sets off a new hire approval flow
        is_enabled:
          type: boolean
          example: true
          description: Specifies if this workflow is enabled
    Workflows:
      title: Workflows
      type: object
      x-box-resource-id: workflows
      x-box-tag: workflows
      description: 'A list of workflows.


        You application must be authorized to use the `Manage Box Relay` application

        scope within the developer console in order to use this resource.'
      allOf:
      - type: object
        description: 'The part of an API response that describes marker

          based pagination'
        properties:
          limit:
            description: 'The limit that was used for these entries. This will be the same as the

              `limit` query parameter unless that value exceeded the maximum value

              allowed. The maximum value varies by API.'
            example: 1000
            type: integer
            format: int64
          next_marker:
            description: The marker for the start of the next page of results.
            example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
            type: string
            nullable: true
          prev_marker:
            description: The marker for the start of the previous page of results.
            example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
            type: string
            nullable: true
      - properties:
          entries:
            type: array
            description: A list of workflows
            items:
              $ref: '#/components/schemas/Workflow'
    ClientError:
      title: Client error
      type: object
      x-box-resource-id: client_error
      description: A generic error
      properties:
        type:
          description: error
          example: error
          type: string
          enum:
          - error
          nullable: false
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
          nullable: false
        code:
          description: A Box-specific error code
          example: item_name_invalid
          type: string
          enum:
          - created
          - accepted
          - no_content
          - redirect
          - not_modified
          - bad_request
          - unauthorized
          - forbidden
          - not_found
          - method_not_allowed
          - conflict
          - precondition_failed
          - too_many_requests
          - internal_server_error
          - unavailable
          - item_name_invalid
          - insufficient_scope
        message:
          description: A short message describing the error.
          example: Method Not Allowed
          type: string
          nullable: false
        context_info:
          description: 'A free-form object that contains additional context

            about the error. The possible fields are defined on

            a per-endpoint basis. `message` is only one example.'
          type: object
          nullable: true
          properties:
            message:
              type: string
              description: More details on the error.
              example: Something went wrong.
        help_url:
          description: A URL that links to more information about why this error occurred.
          example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
          type: string
          nullable: false
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
          nullable: false
    Workflow:
      title: Workflow
      type: object
      x-box-resource-id: workflow
      x-box-variant: standard
      description: 'Box Relay Workflows are objects that represent a named collection of flows.


        Your application must be authorized to use the `Manage Box Relay` application

        scope within the developer console in order to use this resource.'
      allOf:
      - $ref: '#/components/schemas/Workflow--Mini'
      - properties:
          flows:
            type: array
            description: A list of flows assigned to a workflow.
            items:
              type: object
              description: 'A step in a Box Relay Workflow. Each flow contains a `Trigger` and

                a collection of Outcomes to perform once the conditions of a

                `Trigger` are met'
              properties:
                id:
                  type: string
                  description: The identifier of the flow
                  example: '12345'
                type:
                  type: string
                  description: The flow's resource type
                  example: flow
                  enum:
                  - flow
                trigger:
                  allOf:
                  - type: object
                    properties:
                      type:
                        type: string
                        description: The trigger's resource type
                        example: trigger
                        enum:
                        - trigger
                      trigger_type:
                        type: string
                        description: The type of trigger selected for this flow
                        example: WORKFLOW_MANUAL_START
                        enum:
                        - WORKFLOW_MANUAL_START
                      scope:
                        type: array
                        description: List of trigger scopes
                        items:
                          type: object
                          description: Object that describes where and how a Trigger condition is met
                          properties:
                            type:
                              type: string
                              description: The trigger scope's resource type
                              example: trigger_scope
                              enum:
                              - trigger_scope
                            ref:
                              type: string
                              description: Indicates the path of the condition value to check
                              example: /event/source/parameters/folder
                            object:
                              type: object
                              description: The object the `ref` points to
                              properties:
                                type:
                                  type: string
                                  description: The type of the object
                                  example: folder
                                  enum:
                                  - folder
                                id:
                                  type: string
                                  description: The id of the object
                                  example: '12345'
                  - description: Trigger that initiates flow
                outcomes:
                  allOf:
                  - type: array
                    items:
                      type: object
                      description: List of outcomes to perform once the conditions of trigger are met.
                      properties:
                        id:
                          type: string
                          description: The identifier of the outcome
                          example: '12345'
                        type:
                          type: string
                          description: The outcomes resource type
                          example: outcome
                          enum:
                          - outcome
                        name:
                          type: string
                          description: The name of the outcome
                          example: Task Approval Outcome
                        action_type:
                          allOf:
                          - title: Action Type
                            example: assign_task
                            type: string
                            description: The type of outcome
                            enum:
                            - add_metadata
                            - assign_task
                            - copy_file
                            - copy_folder
                            - create_folder
                            - delete_file
                            - delete_folder
                            - lock_file
                            - move_file
                            - move_folder
                            - remove_watermark_file
                            - rename_folder
                            - restore_folder
                            - share_file
                            - share_folder
                            - unlock_file
                            - upload_file
                            - wait_for_task
                            - watermark_file
                            - go_back_to_step
                            - apply_file_classification
                            - apply_folder_classification
                            - send_notification
                          - description: The type of outcome
                        if_rejected:
                          type: array
                          description: 'If `action_type` is `assign_task` and the task is rejected, returns a

                            list of outcomes to complete'
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                description: The identifier of the outcome
                                example: '12345'
                              type:
                                type: string
                                description: The outcomes resource type
                                example: outcome
                                enum:
                                - outcome
                              name:
                                type: string
                                description: The name of the outcome
                                example: Approval Rejection Outcome
                              action_type:
                                allOf:
                                - title: Action Type
                                  example: assign_task
                                  type: string
                                  description: The type of outcome
                                  enum:
                                  - add_metadata
                                  - assign_task
                                  - copy_file
                                  - copy_folder
                                  - create_folder
                                  - delete_file
                                  - delete_folder
                                  - lock_file
                                  - move_file
                                  - move_folder
                                  - remove_watermark_file
                                  - rename_folder
                                  - restore_folder
                                  - share_file
                                  - share_folder
                                  - unlock_file
                                  - upload_file
                                  - wait_for_task
                                  - watermark_file
                                  - go_back_to_step
                                  - apply_file_classification
                                  - apply_folder_classification
                                  - send_notification
                                - description: The type of outcome
                  - description: Actions that are completed once the flow is triggered
                created_at:
                  type: string
                  format: date-time
                  description: When this flow was created
                  example: '2012-12-12T10:53:43-08:00'
                created_by:
                  allOf:
                  - $ref: '#/components/schemas/User--Base'
                  - description: The user who created this flow