openapi: 3.1.0 info: 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