Box User Avatars API

openapi: 3.2.0
info:
  title: Box Platform User Avatars API
  description: '[Box Platform](https://box.dev) provides functionality to provide access to content stored within [Box](https://box.com). 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: User Avatars
  description: 'User avatars are JPG or PNG files

    uploaded to Box to represent the

    user image. They are then displayed

    in the user account.'
  x-box-tag: avatars
paths:
  /users/{user_id}/avatar:
    get:
      operationId: get_users_id_avatar
      x-box-tag: avatars
      summary: Box Get user avatar
      tags:
      - User Avatars
      description: Retrieves an image of a the user's avatar.
      parameters:
      - name: user_id
        description: The ID of the user.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'When an avatar can be found for the user the

            image data will be returned in the body of the

            response.'
          content:
            image/jpg:
              schema:
                type: string
                format: binary
                description: The avatar
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    post:
      operationId: post_users_id_avatar
      x-box-tag: avatars
      summary: Box Add or update user avatar
      tags:
      - User Avatars
      description: Adds or updates a user avatar.
      parameters:
      - name: user_id
        description: The ID of the user.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - pic
              properties:
                pic:
                  type: string
                  format: binary
                  description: 'The image file to be uploaded to Box.

                    Accepted file extensions are `.jpg` or `.png`.

                    The maximum file size is 1MB.'
      responses:
        '200':
          description: '* `ok`: Returns the `pic_urls` object with URLs to existing

            user avatars that were updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAvatar'
        '201':
          description: '* `created`: Returns the `pic_urls` object with URLS to user avatars

            uploaded to Box with the request.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAvatar'
        '400':
          description: "* `bad_request`: Returns an error when:\n    * An image is not included in the request\n    * The uploaded file is empty\n    * The image size exceeds 1024 * 1024 pixels\n    or 1MB\n    * The file extension is other than `.jpg` or `.png`."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: '* `forbidden`: Returns an error if the user does not have permissions

            necessary to upload an avatar or is not activated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: '* `not_found`: Returns an error if the user

            does not exist or cannot be found.'
          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_users_id_avatar
      x-box-tag: avatars
      summary: Box Delete user avatar
      tags:
      - User Avatars
      description: 'Removes an existing user avatar.

        You cannot reverse this operation.'
      parameters:
      - name: user_id
        description: The ID of the user.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: '* `no_content`: Removes the avatar and returns an empty response.'
        '403':
          description: "* `forbidden`: Returned if the user does not have necessary permissions\n or is not activated."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: "* `not_found`: Returned if the user or user avatar does not exist\n or cannot be found."
          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
        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
    UserAvatar:
      title: User avatar
      type: object
      x-box-resource-id: user_avatar
      x-box-tag: avatars
      description: 'A resource holding URLs to the

        avatar uploaded to a Box application.'
      properties:
        pic_urls:
          type: object
          description: Represents an object with user avatar URLs.
          properties:
            small:
              type: string
              description: The location of a small-sized avatar.
              example: 'https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!7B6R5cZLmurEV_xB-KkycPk8Oi7oENUX2O_qUtIuO4342CG IldyCto9hqiQP7uxqYU5V2w63Ft4ln4UVVLDtDZu903OqzkflY2O-Lq00 ubA29xU-RJ6b_KzJEWRYgUhX1zEl3dzWo12g8eWRE2rStf123DF7AYahNqM 1BmLmviL_nODc7SDQHedTXPAjxURUAra5BvtLe7B05AizbNXdPlCNp-LNh _S-eZ_RjDXcGO-MkRWd_3BOMHnvjf450t5BfKoJ15WhEfiMlfXH1tmouHXrsC 66cT6-pzF9E40Iir_zThqSlrFxzP_xcmXzHapr_k-0E2qr2TXp4iC396TSlEw

                '
            large:
              type: string
              description: The location of a large-sized avatar.
              example: 'https://app.box.com/index.php?rm=pic_storage_auth&pic=euks

                pac3kv01!lipGQlQQOtCTCoB6zCOArUjVWLFJtLr5tn6aOZMCybhRx0NNuFQbVI36nw

                jtEk5YjUUz1KVdVuvU2yDhu_ftK_bvxeKP1Ffrx9vKGVvJ-UJc1z32p6n2CmFzzpc

                gSoX4pnPhFgydAL-u9jDspXUGElr-htDG_HPMiE9DZjqDueOxXHy8xe22wbaPAheC

                ao1emv8r_fmufaUgSndeMYmyZj-KqOYsLBrBNgdeiK5tZmPOQggAEUmyQPkrd8W92TQ6sSlIp0r'
            preview:
              type: string
              description: The location of the avatar preview.
              example: 'https://app.box.com/index.php?rm=pic_storage_auth&pic=euks!

                pac3kv01!8UcNPweOOAWj2DtHk_dCQB4wJpzyPkl7mT5nHj5ZdjY92ejYCBBZc95--403b29CW

                k-8hSo_uBjh5h9QG42Ihu-cOZ-816sej1kof3SOm5gjn7qjMAx89cHjUaNK-6XasRqSNboenjZ

                04laZuV9vSH12BZGAYycIZvvQ5R66Go8xG5GTMARf2nBU84c4H_SL5iws-HeBS4oQJWOJh6FBl

                sSJDSTI74LGXqeZb3EY_As34VFC95F10uozoTOSubZmPYylPlaKXoKWk2f9wYQso1ZTN7sh-Gc

                9Kp43zMLhArIWhok0Im6FlRAuWOQ03KYgL-k4L5EZp4Gw6B7uqVRwcBbsTwMIorWq1g'
  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