openapi: 3.1.0
info:
  title: Box Task Assignments API
  description: Needs a description.
paths:
  /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:
    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
    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.
tags:
  - name: Task Assignments