Sample - Box Platform API
POST/tasks

Create task

Creates a single task on a file. This task is not assigned to any user and will need to be assigned separately.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

5 body fields
itemobjectrequired
The file to attach the task to.
actionstringoptional
The action the task assignee will be prompted to do. Must be * `review` defines an approval task that can be approved or, rejected * `complete` defines a general task which can be completed.
Allowed:reviewcompleteDefault:review
messagestringoptional
An optional message to include with the task.
Default:
due_atstringoptional
Defines when the task is due. Defaults to `null` if not provided.
completion_rulestringoptional
Defines which assignees need to complete this task before the task is considered completed. * `all_assignees` (default) requires all assignees to review or approve the task in order for it to be considered completed. * `any_assignee` accepts any one assignee to review or approve the task in order for it to be considered completed.
Allowed:all_assigneesany_assigneeDefault:all_assignees

5 status codes
201Returns the newly created task.
idstringoptional
The unique identifier for this task.
typestringoptional
The value will always be `task`.
Allowed:task
itemobjectoptional
due_atstringoptional
When the task is due.
actionstringoptional
The type of task the task assignee will be prompted to perform.
Allowed:reviewcomplete
messagestringoptional
A message that will be included with the task.
task_assignment_collectionobjectoptional
is_completedbooleanoptional
Whether the task has been completed.
created_byobjectoptional
created_atstringoptional
When the task object was created.
completion_rulestringoptional
Defines which assignees need to complete this task before the task is considered completed. * `all_assignees` requires all assignees to review or approve the task in order for it to be considered completed. * `any_assignee` accepts any one assignee to review or approve the task in order for it to be considered completed.
Allowed:all_assigneesany_assignee
400Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. This may be because the `action` or `completion_rule` are not one of the allowed values.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
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.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
403Returns an error when the user does not have the permission to create a task on the file.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
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.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returns an error when the file could not be found or the user does not have access to the file.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
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.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultAn unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
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.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned: Returned if the request parameters or body is not valid.

  • bad_request when the body does not contain a valid request. This may be because the action or completion_rule are not one of the allowed values. A 403 is returned: Returns an error when the user does not have the permission to create a task on the file. A 404 is returned: Returns an error when the file could not be found or the user does not have access to the file. Any other status is an error: An unexpected client error.