Box

Box Watermarks (Files) API

A watermark is a semi-transparent overlay on an embedded file preview that displays a viewer's email address or user ID and the time of access over the file.

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-watermarks-files-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:
  title: Box Authorize Authorization Watermarks (Files) API
  description: Needs a description.
tags:
- name: Watermarks (Files)
  description: 'A watermark is a semi-transparent

    overlay on an embedded file

    preview that displays a viewer''s email address

    or user ID and the time of access over

    the file.'
  x-box-tag: file_watermarks
paths:
  /files/{file_id}/watermark:
    get:
      operationId: get_files_id_watermark
      summary: Box Get watermark on file
      tags:
      - Watermarks (Files)
      x-box-tag: file_watermarks
      description: Retrieve the watermark for a file.
      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 an object containing information about the

            watermark associated for to this file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watermark'
        '404':
          description: Returns an error if the file does not have a watermark applied.
          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_files_id_watermark
      summary: Box Apply watermark to file
      tags:
      - Watermarks (Files)
      x-box-tag: file_watermarks
      description: Applies or update a watermark on a file.
      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
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - watermark
              properties:
                watermark:
                  type: object
                  description: The watermark to imprint on the file
                  required:
                  - imprint
                  properties:
                    imprint:
                      type: string
                      example: default
                      description: 'The type of watermark to apply.


                        Currently only supports one option.'
                      enum:
                      - default
      responses:
        '200':
          description: 'Returns an updated watermark if a watermark already

            existed on this file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watermark'
        '201':
          description: 'Returns a new watermark if no watermark existed on

            this file yet.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watermark'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    delete:
      operationId: delete_files_id_watermark
      summary: Box Remove watermark from file
      tags:
      - Watermarks (Files)
      x-box-tag: file_watermarks
      description: Removes the watermark from a file.
      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:
        '204':
          description: Removes the watermark and returns an empty response.
        '404':
          description: 'Returns an error if the file did not have

            a watermark applied to it.'
          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
    Watermark:
      title: Watermark
      type: object
      x-box-resource-id: watermark
      x-box-tag: file_watermarks
      description: 'A watermark is a semi-transparent overlay on an embedded file

        preview that displays a viewer''s email address or user ID

        and the time of access over a file''s content'
      properties:
        watermark:
          type: object
          properties:
            created_at:
              type: string
              format: date-time
              description: When this watermark was created
              example: '2012-12-12T10:53:43-08:00'
            modified_at:
              type: string
              format: date-time
              description: When this task was modified
              example: '2012-12-12T10:53:43-08:00'