openapi: 3.2.0
info:
  title: Platform - Documents Attachments API
  version: '1.0'
  contact:
    name: OneTrust Support
    url: https://my.onetrust.com/s/contactsupport
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  description: The Documents API are used to integrate external systems and streamline the flow of data for documents in the OneTrust Platform.
servers:
- url: https://{hostname}
  variables:
    hostname:
      default: hostname
      description: The OneTrust hostname such as app.onetrust.com, app-eu.onetrust.com, app-de.onetrust.com, app-uk.onetrust.com, app-apac.onetrust.com, trial.onetrust.com, or uat.onetrust.com.
tags:
- name: Attachments
  description: The Attachments APIs are used to upload and obtain the location of files uploaded in the OneTrust Platform.
  externalDocs:
    description: OpenAPI 3.1.0 - Download Definition
    url: https://developer.onetrust.com/onetrust/openapi/platform-documents.json
paths:
  /api/document/v2/attachments:
    post:
      operationId: fileUpload
      summary: Upload File
      description: 'Use this API to upload a file up to 64MB to the OneTrust Platform. The response will include the `Id` and `FileName` parameters, which can be used to attach the file to a product within the platform.


        > 🗒 Things to Know

        >

        > - The extension of the uploaded file must be in one of the supported file formats. For more information, see Using the Document Repository.

        > - The `attachment` parameter below includes the following information:

        > - `Parameters & Descriptions` contains details on the list of parameters and expected parameter values. This should be used for reference only.

        > - `Attachment JSON Object` contains the required format in which the parameters and parameter values must be sent in the request.'
      tags:
      - Attachments
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/platform-documents.json
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AttachmentMultipartRequest'
            examples:
              default:
                description: default
                value:
                  file: '@/path/to/your/file.pdf'
                  attachment: '{"FileName":"document.pdf","Type": 30,"RefIds":["beb90499-ea60-47aa-8ed8-966f2df5f2e8"],"IsInternal":true, "Name": "Important Document", "Comments": "This is a confidential document"}'
            encoding:
              file:
                contentType: application/octet-stream
              attachment:
                contentType: application/json
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: "Too Many Requests. \nFor more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview)."
          headers:
            Retry-After:
              schema:
                description: The number of seconds after which requests will be allowed again.
                format: int32
            ot-period:
              schema:
                description: The unit of time for which the rate limit applies
                enum:
                - HOUR
                - MINUTE
            ot-ratelimit-event-id:
              schema:
                description: The unique identifier for the rate-limiting event.
                format: uuid
            ot-request-made:
              schema:
                description: The number of requests made within the specified period.
                format: int32
            ot-requests-allowed:
              schema:
                description: The number of requests allowed within the specified period.
                format: int32
        '500':
          description: Internal Server Error
      security:
      - OAUTH2:
        - ATTACHMENT
  /api/document/v3/attachments/{attachmentId}/content:
    get:
      operationId: fileLocation
      summary: Get File Location
      description: Use this API to obtain the location of an uploaded file. The location can be identified by the `downloadUrl` parameter included in the response.
      tags:
      - Attachments
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/platform-documents.json
      parameters:
      - name: attachmentId
        in: path
        description: The unique identifier of the uploaded file.
        required: true
        schema:
          type: string
          format: uuid
        example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentProcessInitResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: "Too Many Requests. \nFor more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview)."
          headers:
            Retry-After:
              schema:
                description: The number of seconds after which requests will be allowed again.
                format: int32
            ot-period:
              schema:
                description: The unit of time for which the rate limit applies
                enum:
                - HOUR
                - MINUTE
            ot-ratelimit-event-id:
              schema:
                description: The unique identifier for the rate-limiting event.
                format: uuid
            ot-request-made:
              schema:
                description: The number of requests made within the specified period.
                format: int32
            ot-requests-allowed:
              schema:
                description: The number of requests allowed within the specified period.
                format: int32
        '500':
          description: Internal Server Error
      security:
      - OAUTH2:
        - DSAR
        - ATTACHMENT_READ
        - DATA_DISCOVERY
components:
  schemas:
    AttachmentMultipartRequest:
      type: object
      properties:
        attachment:
          description: The details of the file.
          type: object
          oneOf:
          - $ref: '#/components/schemas/AttachmentCreateRequestV2'
          - type: string
            format: application/json
            example: '{"FileName":"document.pdf","Type":30,"RefIds":["beb90499-ea60-47aa-8ed8-966f2df5f2e8"],"IsInternal":true,"Name":"Important Document","Comments":"This is a confidential document"}'
            title: Attachment JSON Object - Required Format
        file:
          description: The file to upload to the OneTrust Platform. The file must be 64MB or less.
          type: string
          format: binary
          contentMediaType: application/octet-stream
      required:
      - attachment
      - file
    SharedAccessParams:
      type: object
      properties:
        storageAccountName:
          description: The name of the storage account for the file.
          type: string
          example: trialapp4533.blob.core.windows.net
        containerName:
          description: The name of the container where the file is stored.
          type: string
          example: stage
        fileName:
          description: The name of the file in storage.
          type: string
          example: d7facfb2-7906-435a-8e94-95a39232632b
        signature:
          description: The access token for the file.
          type: string
          example: sv=2024-08-04&se=2025-06-06T17%3A05%3A07Z&sr=b&sp=r&sig=WRS6X5eKVLHjDqJvpFQuw6BA23hDB0NQviyfmAau%2FEc%3D
    AttachmentProcessInitResponse:
      type: object
      properties:
        requestType:
          description: The status of the request.
          type: string
          example: CREATED
          enum:
          - CREATED
          - RENEWED
          - OVERRIDE
          - RETRY
          - DIRECTORY
        uploadParams:
          description: The details needed to access the file.
          $ref: '#/components/schemas/SharedAccessParams'
        statusUrl:
          description: The URL to check the status of the request.
          type: string
          example: /document/v3/attachments/status/d7facfb2-7906-435a-8e94-95a39232632b
        downloadUrl:
          description: The URL to download the file.
          type: string
          example: https://trialapp4533.blob.core.windows.net/stage/d7facfb2-7906-435a-8e94-95a39232632b?sv=2024-08-04&se=2025-06-06T17%3A05%3A07Z&sr=b&sp=r&sig=WRS6X5eKVLHjDqJvpFQuw6BA23hDB0NQviyfmAau%2FEc%3D
    AttachmentResponse:
      type: object
      properties:
        Id:
          description: The unique identifier of the uploaded file.
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        Name:
          description: The display name of the file.
          type: string
          example: Important Document
        FileName:
          description: The name of the file, including its extension.
          type: string
          example: document.pdf
        Comments:
          description: The notes about the file.
          type: string
          example: This is a confidential document
        FileSize:
          description: The size of the file in bytes.
          type: integer
          format: int64
          example: 1048576
        FileType:
          description: The type of file, based on its extension.
          type: string
          example: pdf
          enum:
          - pdf
          - doc
          - docx
          - txt
          - png
          - jpg
          - jpeg
          - csv
        CreatedById:
          description: The unique identifier of the user who uploaded the file.
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        CreatedBy:
          description: The name of the user who uploaded the file.
          type: string
          example: John Doe
        CreatedDT:
          description: The date and time when the file was uploaded.
          type: string
          format: date-time
          example: '2024-03-20T10:30:00'
        Type:
          description: The number associated with the content type of the file, as listed within Show Details.
          type: integer
          format: int64
          default: '30'
          enum:
          - '10'
          - '20'
          - '30'
          - '40'
          - '50'
          - '60'
          - '70'
          - '80'
          - '90'
          - '100'
          - '110'
          - '120'
          - '130'
          - '140'
          - '150'
          - '160'
          - '170'
          - '180'
          - '190'
          - '200'
          - '210'
          x-enumDescriptions:
            '10': Question
            '20': LogoBranding
            '21': TitleBranding
            '30': DSAR
            '50': Inventory
            '60': Assessment Question
            '70': Incident
            '80': Export Control
            '90': Export Engagement
            '100': Export Assessment Exchange Request
            '110': Risk
            '120': Export Vendor Contract
            '130': Audit Management
            '140': WOPI EPM Office Files
            '150': Data Governance
            '160': Template Question
            '161': Template Export
            '170': Glossary
            '180': Attribute Manager Export
            '190': WB Investigation Attachment
            '200': Custom Object Document
            '210': Continuous Monitoring
            '220': OT Insights Bulk Export
        RefId:
          description: The unique identifier of the record associated with the attached file.
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        IsInternal:
          description: This flag indicates whether the file is marked for internal use.
          type: boolean
          example: true
    AttachmentCreateRequestV2:
      type: object
      properties:
        FileName:
          description: The name of the file, including its extension.
          type: string
          example: document.pdf
          maxLength: 260
          minLength: 0
        Name:
          description: The display name of the file.
          type: string
          example: Important Document
          maxLength: 260
          minLength: 0
        RefIds:
          description: The unique identifier of the record associated with the attached file.
          type: array
          items:
            type: string
            format: uuid
            description: <p>This needs to be a valid UUID. RefIds link files with entities. For e.g. To link a file with an assessment, use 'AssessmentId' as RefId.<p>
            example:
            - 123e4567-e89b-12d3-a456-426614174000
          maxItems: 1
        Comments:
          description: The notes about the file.
          type: string
          example: This is a confidential document
          maxLength: 1073741823
        Type:
          description: The number associated with the content type of the file, as listed within Show Details.
          type: integer
          format: int64
          default: '30'
          enum:
          - '10'
          - '20'
          - '30'
          - '40'
          - '50'
          - '60'
          - '70'
          - '80'
          - '90'
          - '100'
          - '110'
          - '120'
          - '130'
          - '140'
          - '150'
          - '160'
          - '170'
          - '180'
          - '190'
          - '200'
          - '210'
          x-enumDescriptions:
            '10': Question
            '20': LogoBranding
            '21': TitleBranding
            '30': DSAR
            '50': Inventory
            '60': Assessment Question
            '70': Incident
            '80': Export Control
            '90': Export Engagement
            '100': Export Assessment Exchange Request
            '110': Risk
            '120': Export Vendor Contract
            '130': Audit Management
            '140': WOPI EPM Office Files
            '150': Data Governance
            '160': Template Question
            '161': Template Export
            '170': Glossary
            '180': Attribute Manager Export
            '190': WB Investigation Attachment
            '200': Custom Object Document
            '210': Continuous Monitoring
            '220': OT Insights Bulk Export
        IsInternal:
          description: This flag indicates whether the file is marked for internal use.
          type: boolean
          example: true
          default: 'true'
        Encrypt:
          description: This flag indicates whether the file should be encrypted.
          type: boolean
          example: true
          default: 'true'
      required:
      - FileName
      - RefIds
      - Type
      title: Parameters & Descriptions - Reference Only
  securitySchemes:
    OAUTH2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{hostname}/api/access/v1/oauth/token
          scopes:
            ATTACHMENT: Grants access to view and manage attachments
            ATTACHMENT_READ: Grants access to view attachments
x-onetrust:
  spec-label: OpenAPI 3.1.0
x-readme:
  explorer-enabled: false
  proxy-enabled: false
  metrics-enabled: false