Box Task Assignments API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Task Assignments API
  description: Needs a description.
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:
    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
    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
    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'