OpenAPI Specification
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