Box Tasks API

openapi: 3.2.0
info:
  title: Box Platform Tasks 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: Tasks
  description: 'Tasks allow users to request collaborators on a file

    to review a file or complete a piece of work.

    Tasks can be used by developers to create file-centric workflows.'
  x-box-tag: tasks
paths:
  /files/{file_id}/tasks:
    get:
      operationId: get_files_id_tasks
      summary: Box List tasks on file
      description: 'Retrieves a list of all the tasks for a file. This

        endpoint does not support pagination.'
      tags:
      - Tasks
      x-box-tag: tasks
      x-box-sanitized: true
      parameters:
      - name: file_id
        description: 'The unique identifier that represents a file.


          The ID for any file can be determined

          by visiting a file in the web application

          and copying the ID from the URL. For example,

          for the URL `https://*.app.box.com/files/123`

          the `file_id` is `123`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returns a list of tasks on a file.


            If there are no tasks on this file an empty collection is returned

            instead.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tasks'
        '404':
          description: 'Returns an error when the file could not be found or the user does not

            have access to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returns an error when the `file_id` was not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '500':
          description: 'Returns an error when an attempt was made to retrieve tasks for the file

            with ID `0`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /tasks:
    post:
      operationId: post_tasks
      tags:
      - Tasks
      summary: Box Create task
      x-box-tag: tasks
      x-box-sanitized: true
      description: 'Creates a single task on a file. This task is not assigned to any user and

        will need to be assigned separately.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - item
              properties:
                item:
                  type: object
                  description: The file to attach the task to.
                  properties:
                    id:
                      type: string
                      description: The ID of the file
                      example: '11446498'
                    type:
                      type: string
                      description: '`file`'
                      example: file
                      enum:
                      - file
                action:
                  type: string
                  description: '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'
                  example: review
                  default: review
                  enum:
                  - review
                  - complete
                message:
                  type: string
                  default: ''
                  description: An optional message to include with the task.
                  example: Please review
                due_at:
                  type: string
                  format: date-time
                  description: 'Defines when the task is due. Defaults to `null` if not

                    provided.'
                  example: '2012-12-12T10:53:43-08:00'
                completion_rule:
                  type: string
                  description: '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 the task in order for it to be considered completed.

                    * `any_assignee` accepts any one assignee to review or

                    approve the the task in order for it to be considered completed.'
                  example: all_assignees
                  default: all_assignees
                  enum:
                  - all_assignees
                  - any_assignee
      responses:
        '201':
          description: Returns the newly created task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: '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.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: 'Returns an error when the user does not have the permission to create a

            task on the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returns an error when the file could not be found or the user does not

            have access to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /tasks/{task_id}:
    get:
      operationId: get_tasks_id
      summary: Box Get task
      tags:
      - Tasks
      x-box-tag: tasks
      x-box-sanitized: true
      description: Retrieves information about a specific task.
      parameters:
      - name: task_id
        description: The ID of the task.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns a task object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: 'Returns an error when the task could not be found or the user does not

            have access to the file the task is assigned to.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    put:
      operationId: put_tasks_id
      tags:
      - Tasks
      summary: Box Update task
      x-box-tag: tasks
      x-box-sanitized: true
      description: 'Updates a task. This can be used to update a task''s configuration, or to

        update its completion state.'
      parameters:
      - name: task_id
        description: The ID of the task.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: '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'
                  example: review
                  enum:
                  - review
                  - complete
                message:
                  type: string
                  description: The message included with the task.
                  example: Please review
                due_at:
                  type: string
                  format: date-time
                  description: When the task is due at.
                  example: '2012-12-12T10:53:43-08:00'
                completion_rule:
                  type: string
                  description: '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 the task in order for it to be considered completed.

                    * `any_assignee` accepts any one assignee to review or

                    approve the the task in order for it to be considered completed.'
                  example: all_assignees
                  enum:
                  - all_assignees
                  - any_assignee
      responses:
        '200':
          description: Returns the updated task object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: '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.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: 'Returns an error when the user does not have the permission to update a

            task on the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returns an error when the file could not be found or the user does not

            have access to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    delete:
      operationId: delete_tasks_id
      tags:
      - Tasks
      summary: Box Remove task
      x-box-tag: tasks
      x-box-sanitized: true
      description: Removes a task from a file.
      parameters:
      - name: task_id
        description: The ID of the task.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Returns an empty response when the task was successfully deleted.
        '404':
          description: 'Returns an error when the task could not be found or the user does not

            have access to the file the task is assigned to.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    TaskAssignments:
      title: Task assignments
      type: object
      x-box-resource-id: task_assignments
      x-box-tag: task_assignments
      description: A list of task assignments
      properties:
        total_count:
          description: The total number of items in this collection.
          example: 100
          type: integer
          format: int64
        entries:
          type: array
          description: A list of task assignments
          items:
            $ref: '#/components/schemas/TaskAssignment'
    User--Mini:
      title: User (Mini)
      type: object
      x-box-resource-id: user--mini
      x-box-variant: mini
      description: 'A mini representation of a user, as can be returned when nested within other

        resources.'
      allOf:
      - $ref: '#/components/schemas/User--Base'
      - properties:
          name:
            type: string
            description: The display name of this user
            example: Aaron Levie
            maxLength: 50
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
    File--Base:
      title: File (Base)
      type:
      - object
      - 'null'
      x-box-resource-id: file--base
      x-box-sanitized: true
      x-box-tag: files
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a file, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: 'The unique identifier that represent a file.


            The ID for any file can be determined

            by visiting a file in the web application

            and copying the ID from the URL. For example,

            for the URL `https://*.app.box.com/files/123`

            the `file_id` is `123`.'
          example: '12345'
        etag:
          type:
          - string
          - 'null'
          example: '1'
          description: 'The HTTP `etag` of this file. This can be used within some API

            endpoints in the `If-Match` and `If-None-Match` headers to only

            perform changes on the file if (no) changes have happened.'
        type:
          type: string
          description: '`file`'
          example: file
          enum:
          - file
    Tasks:
      title: Tasks
      type: object
      x-box-resource-id: tasks
      x-box-tag: tasks
      description: A list of tasks
      properties:
        total_count:
          description: 'One greater than the offset of the last entry in the entire collection.

            The total number of entries in the collection may be less than

            `total_count`.'
          example: 5000
          type: integer
          format: int64
        entries:
          type: array
          description: A list of tasks
          items:
            $ref: '#/components/schemas/Task'
    Task:
      title: Task
      type: object
      x-box-resource-id: task
      x-box-tag: tasks
      description: 'A task allows for file-centric workflows within Box. Users can

        create tasks on files and assign them to other users for them to complete the

        tasks.'
      properties:
        id:
          type: string
          description: The unique identifier for this task
          example: '11446498'
        type:
          type: string
          description: '`task`'
          example: task
          enum:
          - task
        item:
          allOf:
          - $ref: '#/components/schemas/File--Mini'
          - description: The file associated with the task
        due_at:
          type: string
          format: date-time
          description: When the task is due
          example: '2012-12-12T10:53:43-08:00'
        action:
          type: string
          example: review
          description: 'The type of task the task assignee will be prompted to

            perform.'
          enum:
          - review
          - complete
        message:
          type: string
          description: A message that will be included with the task
          example: Legal review
        task_assignment_collection:
          allOf:
          - $ref: '#/components/schemas/TaskAssignments'
          - description: 'A collection of task assignment objects

              associated with the task'
        is_completed:
          type: boolean
          description: Whether the task has been completed
          example: true
        created_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who created the task
        created_at:
          type: string
          format: date-time
          description: When the task object was created
          example: '2012-12-12T10:53:43-08:00'
        completion_rule:
          type: string
          description: 'Defines which assignees need to complete this task before the task

            is considered completed.


            * `all_assignees` requires all assignees to review or

            approve the the task in order for it to be considered completed.

            * `any_assignee` accepts any one assignee to review or

            approve the the task in order for it to be considered completed.'
          example: all_assignees
          enum:
          - all_assignees
          - any_assignee
    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
    FileVersion--Mini:
      title: File version (Mini)
      type: object
      x-box-resource-id: file_version--mini
      x-box-variant: mini
      description: 'A mini representation of a file version, used when

        nested within another resource.'
      allOf:
      - $ref: '#/components/schemas/FileVersion--Base'
      - properties:
          sha1:
            type: string
            description: The SHA1 hash of this version of the file.
            example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
    FileVersion--Base:
      title: File version (Base)
      type: object
      x-box-resource-id: file_version--base
      x-box-sanitized: true
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a file version, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: The unique identifier that represent a file version.
          example: '12345'
        type:
          type: string
          description: '`file_version`'
          example: file_version
          enum:
          - file_version
    TaskAssignment:
      title: Task assignment
      type: object
      x-box-resource-id: task_assignment
      x-box-tag: task_assignments
      description: A task assignment defines which task is assigned to which user to complete.
      properties:
        id:
          type: string
          description: The unique identifier for this task assignment
          example: '11446498'
        type:
          type: string
          description: '`task_assignment`'
          example: task_assignment
          enum:
          - task_assignment
        item:
          allOf:
          - $ref: '#/components/schemas/File--Mini'
          - description: The file that the task has been assigned to.
        assigned_to:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user that the task has been assigned to.
        message:
          type: string
          example: Please review
          description: 'A message that will is included with the task

            assignment. This is visible to the assigned user in the web and mobile

            UI.'
        completed_at:
          type: string
          format: date-time
          description: 'The date at which this task assignment was

            completed. This will be `null` if the task is not completed yet.'
          example: '2012-12-12T10:53:43-08:00'
        assigned_at:
          type: string
          format: date-time
          description: The date at which this task was assigned to the user.
          example: '2012-12-12T10:53:43-08:00'
        reminded_at:
          type: string
          format: date-time
          description: 'The date at which the assigned user was reminded of this task

            assignment.'
          example: '2012-12-12T10:53:43-08:00'
        resolution_state:
          type: string
          description: 'The current state of the assignment. The available states depend on

            the `action` value of the task object.'
          example: incomplete
          enum:
          - completed
          - incomplete
          - approved
          - rejected
        assigned_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who assigned this task.
    File--Mini:
      title: File (Mini)
      type:
      - object
      - 'null'
      x-box-resource-id: file--mini
      x-box-variant: mini
      description: 'A mini representation of a file, used when

        nested under another resource.'
      allOf:
      - $ref: '#/components/schemas/File--Base'
      - properties:
          sequence_id:
            allOf:
            - type:
              - string
              - 'null'
              example: '3'
              description: 'A numeric identifier that represents the most recent user event

                that has been applied to this item.


                This can be used in combination with the `GET /events`-endpoint

                to filter out user events that would have occurred before this

                identifier was read.


                An example would be where a Box Drive-like application

                would fetch an item via the API, and then listen to incoming

                user events for changes to the item. The application would

                ignore any user events where the `sequence_id` in the event

                is smaller than or equal to the `sequence_id` in the originally

                fetched resource.'
            - {}
          name:
            type: string
            description: The name of the file
            example: Contract.pdf
          sha1:
            type: string
            format: digest
            example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
            description: 'The SHA1 hash of the file. This can be used to compare the contents

              of a file on Box with a local file.'
          file_version:
            allOf:
            - $ref: '#/components/schemas/FileVersion--Mini'
            - description: The information about the current version of the file.
    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