openapi: 3.1.0 info: title: Box Workflows API description: Needs a description. 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 not valid. * `workflow_is_not_enabled` when the workflow is not enabled * `workflow_not_active_on_provided_folder` when the workflow is not enabled for the specified folder id * `parameters_provided_do_not_match_target_outcome` when the provided 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. * `insufficient_access` when the user does not have access rights to file or folder * `missing_relay_full_access` when the user does not have access to Relay 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: 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 tags: - name: Workflows