Box Task Assignments API

openapi: 3.2.0
info:
  title: Box Platform Task Assignments 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: Task Assignments
  description: 'A task assignment defines which

    task is assigned to which user to complete.'
  x-box-tag: task_assignments
paths:
  /tasks/{task_id}/assignments:
    get:
      operationId: get_tasks_id_assignments
      summary: Box List task assignments
      tags:
      - Task Assignments
      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'
  /task_assignments:
    post:
      operationId: post_task_assignments
      summary: Box Assign task
      tags:
      - Task Assignments
      x-box-tag: task_assignments
      x-box-sanitized: true
      description: 'Assigns a task to a user.


        A task can be assigned to more than one user by creating multiple

        assignments.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - task
              - assign_to
              properties:
                task:
                  type: object
                  description: The task to assign to a user.
                  required:
                  - id
                  - type
                  properties:
                    id:
                      type: string
                      description: The ID of the task
                      example: '11446498'
                    type:
                      type: string
                      description: The type of the item to assign.
                      example: task
                      enum:
                      - task
                assign_to:
                  type: object
                  description: The user to assign the task to.
                  properties:
                    id:
                      type: string
                      description: 'The ID of the user to assign to the

                        task.


                        To specify a user by their email

                        address use the `login` parameter.'
                      example: '3242343'
                    login:
                      type: string
                      description: 'The email address of the user to assign to the task.

                        To specify a user by their user ID please use the `id` parameter.'
                      example: john@example.com
      responses:
        '201':
          description: Returns a new task assignment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskAssignment'
        '403':
          description: 'Returns an error if a change is attempted for a completed task or the user

            does not have access to the item linked to the task for the given task

            assignment.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Returns an error when the task cannot be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '500':
          description: 'Returns an error if any of the IDs for this request were not valid, or if

            the targeted 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'
  /task_assignments/{task_assignment_id}:
    get:
      operationId: get_task_assignments_id
      summary: Box Get task assignment
      tags:
      - Task Assignments
      x-box-tag: task_assignments
      x-box-sanitized: true
      description: Retrieves information about a task assignment.
      parameters:
      - name: task_assignment_id
        description: The ID of the task assignment.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returns a task assignment, specifying who the task has been assigned to

            and by whom.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskAssignment'
        '404':
          description: 'Returns an error when the task assignment 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_task_assignments_id
      summary: Box Update task assignment
      tags:
      - Task Assignments
      x-box-tag: task_assignments
      x-box-sanitized: true
      description: 'Updates a task assignment. This endpoint can be

        used to update the state of a task assigned to a user.'
      parameters:
      - name: task_assignment_id
        description: The ID of the task assignment.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: An optional message by the assignee that can be added to the task.
                  example: Looks good to me
                resolution_state:
                  type: string
                  description: 'The state of the task assigned to the user.


                    * For a task with an `action` value of `complete` this can be

                    `incomplete` or `completed`.

                    * For a task with an `action` of `review` this can be

                    `incomplete`, `approved`, or `rejected`.'
                  example: completed
                  enum:
                  - completed
                  - incomplete
                  - approved
                  - rejected
      responses:
        '200':
          description: Returns the updated task assignment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskAssignment'
        '400':
          description: 'Returns an error if a resolution state is incompatible with the action

            type of the task.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returns an error when the task assignment 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'
    delete:
      operationId: delete_task_assignments_id
      summary: Box Unassign task
      tags:
      - Task Assignments
      x-box-tag: task_assignments
      x-box-sanitized: true
      description: Deletes a specific task assignment.
      parameters:
      - name: task_assignment_id
        description: The ID of the task assignment.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'Returns an empty response when the task

            assignment was successfully deleted.'
        '404':
          description: 'Returns an error if the task assignment for the given ID does not exist

            or is inaccessible to your account.'
          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
    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