Box

Box Tasks API

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.

Documentation GitHub OpenAPI

Documentation

https://developer.box.com/reference/get-authorize

https://developer.box.com/reference/post-oauth2-token

https://developer.box.com/reference/post-files-id-copy

https://developer.box.com/reference/post-file-requests-id-copy

https://developer.box.com/reference/post-folders-id-copy

https://developer.box.com/reference/post-folder-locks

https://developer.box.com/reference/post-metadata-templates-schema

https://developer.box.com/reference/post-metadata-cascade-policies

https://developer.box.com/reference/post-metadata-queries-execute-read

https://developer.box.com/reference/post-comments

https://developer.box.com/reference/post-collaborations

https://developer.box.com/reference/post-tasks

https://developer.box.com/reference/post-task-assignments

https://developer.box.com/reference/put-files-id--add-shared-link

https://developer.box.com/reference/put-folders-id--add-shared-link

https://developer.box.com/reference/post-web-links

https://developer.box.com/reference/put-web-links-id--add-shared-link

https://developer.box.com/reference/post-users

https://developer.box.com/reference/post-invites

https://developer.box.com/reference/post-groups

https://developer.box.com/reference/post-group-memberships

https://developer.box.com/reference/post-webhooks

https://developer.box.com/reference/post-files-id-metadata-global-boxSkillsCards

https://developer.box.com/reference/options-events

https://developer.box.com/reference/get-collections-id

https://developer.box.com/reference/get-recent-items

https://developer.box.com/reference/post-retention-policies

https://developer.box.com/reference/post-retention-policy-assignments

https://developer.box.com/reference/post-legal-hold-policies

https://developer.box.com/reference/post-legal-hold-policy-assignments

https://developer.box.com/reference/get-file-version-retentions-id

https://developer.box.com/reference/get-file-version-legal-holds-id

https://developer.box.com/reference/post-shield-information-barriers-change-status

https://developer.box.com/reference/post-shield-information-barrier-reports

https://developer.box.com/reference/post-shield-information-barrier-segments

https://developer.box.com/reference/post-shield-information-barrier-segment-members

https://developer.box.com/reference/post-shield-information-barrier-segment-restrictions

https://developer.box.com/reference/get-device-pinners-id

https://developer.box.com/reference/post-terms-of-services

https://developer.box.com/reference/post-terms-of-service-user-statuses

https://developer.box.com/reference/post-collaboration-whitelist-entries

https://developer.box.com/

Specifications

https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-tasks-api-openapi.yml

Other Resources

https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/graphql/box-graphql.md

OpenAPI Specification

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Tasks API
  description: Needs a description.
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'
  /tasks/{task_id}/assignments:
    get:
      operationId: get_tasks_id_assignments
      summary: Box List task assignments
      tags:
      - Tasks
      x-box-tag: task_assignments
      x-box-sanitized: true
      description: Lists all of the assignments for a given 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 collection of task assignment defining what task on

            a file has been assigned to which users and by who.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskAssignments'
        '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'
        '500':
          description: 'Returns an error if the task assignment ID was omitted in

            the request.'
          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
    File--Base:
      title: File (Base)
      type: object
      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
      nullable: true
      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
          nullable: false
          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
          example: '1'
          nullable: true
          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
          nullable: false
    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
    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
    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
            nullable: false
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
            nullable: false
    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'
    File--Mini:
      title: File (Mini)
      type: object
      x-box-resource-id: file--mini
      x-box-variant: mini
      description: 'A mini representation of a file, used when

        nested under another resource.'
      nullable: true
      allOf:
      - $ref: '#/components/schemas/File--Base'
      - properties:
          sequence_id:
            allOf:
            - type: string
              example: '3'
              nullable: true
              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.'
            - nullable: false
          name:
            type: string
            description: The name of the file
            example: Contract.pdf
          sha1:
            type: string
            format: digest
            nullable: false
            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.
    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.
    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
          nullable: false
          description: The unique identifier that represent a file version.
          example: '12345'
        type:
          type: string
          description: '`file_version`'
          example: file_version
          enum:
          - file_version
          nullable: false
    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
    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'