Box Workflows API

openapi: 3.2.0
info:
  title: Box Platform Workflows API
  description: Box Platform provides functionality to provide access to content stored within Box. It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.
  termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
  contact:
    name: Box, Inc
    url: https://box.dev
    email: devrel@box.com
  license:
    name: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: 2.0.0
  x-box-commit-hash: '5819125043'
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server
security:
- OAuth2Security: []
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
      - name: trigger_type
        description: Type of trigger to search for.
        example: WORKFLOW_MANUAL_START
        in: query
        required: false
        schema:
          type: string
      - 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:
    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
    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
    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
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
        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
        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
          - 'null'
          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
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
    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
            - 'null'
          prev_marker:
            description: The marker for the start of the previous page of results.
            example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
            type:
            - string
            - 'null'
      - properties:
          entries:
            type: array
            description: A list of workflows
            items:
              $ref: '#/components/schemas/Workflow'
    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
          enum:
          - user
  securitySchemes:
    OAuth2Security:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://account.box.com/api/oauth2/authorize
          tokenUrl: https://api.box.com/oauth2/token
          scopes:
            root_readonly: Read all files and folders stored in Box
            root_readwrite: Read and write all files and folders stored in Box
            manage_app_users: Provision and manage app users
            manage_managed_users: Provision and manage managed users
            manage_groups: Manage an enterprise's groups
            manage_webhook: Create webhooks programmatically through the API
            manage_enterprise_properties: Manage enterprise properties
            manage_data_retention: Manage data retention polices
            manage_legal_hold: Manage Legal Holds
externalDocs:
  description: Box Developer Documentation
  url: https://developer.box.com