Wegalvanize Attachments API

openapi: 3.2.0
info:
  title: HighBond API Reference Attachments API
  version: 1.1.0
  description: Welcome to the API documentation for HighBond.
  x-logo:
    url: ./assets/logo.png
    altText: HighBond Logo
servers:
- url: '{protocol}://{server}/v1'
  variables:
    protocol:
      default: https
    server:
      default: apis-us.highbond.com
      enum:
      - apis-us.highbond.com
      - apis-ca.highbond.com
      - apis-eu.highbond.com
      - apis-ap.highbond.com
      - apis-au.highbond.com
      - apis-af.highbond.com
      - apis-sa.highbond.com
      - apis-jp.highbond.com
security:
- bearerToken: []
tags:
- name: Attachments
  description: Attachments are supporting files linked to Controls and Control Tests.
paths:
  /orgs/{org_id}/control_tests/{id}/attachments:
    get:
      tags:
      - Attachments
      operationId: getControlTestAttachments
      summary: List control test attachments
      description: 'Returns a paginated list of file attachments linked to the specified control test.


        Results are returned in JSON:API format. Use the `links.prev` and `links.next` URLs in the response to navigate between pages.'
      parameters:
      - $ref: '#/components/parameters/orgIdParam'
      - $ref: '#/components/parameters/resourceIdParam'
      - $ref: '#/components/parameters/attachmentSparseFieldsetParams'
      - $ref: '#/components/parameters/pageSizeParam'
      - $ref: '#/components/parameters/pageNumberEncodedParam'
      responses:
        '200':
          description: OK.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetControlTestAttachmentsResponse'
              example:
                data:
                - id: '56'
                  type: attachments
                  attributes:
                    attachment_file_name: report.pdf
                    attachment_content_type: application/pdf
                    attachable_type: control_test
                    attachable_id: 123
                    audit_id: 358
                    parent_id: null
                    download_url: https://www.example.com/path-to-file/report.pdf
                  relationships:
                    user:
                      data:
                        id: yvqdNCtv8TeM47WQtzau
                        type: users
                links:
                  prev: null
                  next: /v1/orgs/12345/control_tests/123/attachments?page[size]=50&page[number]=Mg==
        '400':
          $ref: '#/components/responses/MissingResourceId'
        '401':
          $ref: '#/components/responses/BadCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/NotJsonapiMediaType'
  /orgs/{org_id}/controls/{id}/attachments:
    get:
      tags:
      - Attachments
      operationId: getControlAttachments
      summary: List control attachments
      description: 'Returns a paginated list of file attachments linked to the specified control.


        Results are returned in JSON:API format. Use the `links.prev` and `links.next` URLs in the response to navigate between pages.'
      parameters:
      - $ref: '#/components/parameters/orgIdParam'
      - $ref: '#/components/parameters/resourceIdParam'
      - $ref: '#/components/parameters/attachmentSparseFieldsetParams'
      - $ref: '#/components/parameters/pageSizeParam'
      - $ref: '#/components/parameters/pageNumberEncodedParam'
      responses:
        '200':
          description: OK.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetControlAttachmentsResponse'
              example:
                data:
                - id: '56'
                  type: attachments
                  attributes:
                    attachment_file_name: report.pdf
                    attachment_content_type: application/pdf
                    attachable_type: control
                    attachable_id: 456
                    audit_id: 358
                    parent_id: null
                    download_url: https://www.example.com/path-to-file/report.pdf
                  relationships:
                    user:
                      data:
                        id: yvqdNCtv8TeM47WQtzau
                        type: users
                links:
                  prev: null
                  next: /v1/orgs/12345/controls/456/attachments?page[size]=50&page[number]=Mg==
        '400':
          $ref: '#/components/responses/MissingResourceId'
        '401':
          $ref: '#/components/responses/BadCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/NotJsonapiMediaType'
  /orgs/{org_id}/attachments/{id}/download:
    get:
      tags:
      - Attachments
      operationId: downloadAttachment
      summary: Download an attachment
      description: 'Download an attachment file by attachment ID.


        Returns `200 OK` with the file content when the attachment is stored locally, or `302 Found` with a `Location` header pointing to a pre-signed S3 URL when the file is stored remotely.'
      parameters:
      - $ref: '#/components/parameters/orgIdParam'
      - $ref: '#/components/parameters/resourceIdParam'
      responses:
        '200':
          description: OK. Returns the attachment file directly when it is stored locally.
          content: {}
        '302':
          description: Found. Redirects to a pre-signed S3 URL to download the attachment file.
          headers:
            Location:
              description: Pre-signed S3 URL to download the attachment file.
              schema:
                type: string
                format: uri
                example: https://example-bucket.s3.amazonaws.com/attachments/report.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...
        '400':
          $ref: '#/components/responses/MissingResourceId'
        '401':
          $ref: '#/components/responses/BadCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/NotJsonapiMediaType'
components:
  responses:
    NotFound:
      description: Not found.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - status: '404'
              title: Not Found
              detail: The requested resource does not exist.
    NotJsonapiMediaType:
      description: Unsupported media type.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - status: 415
              code: unsupported_media_type
              title: Unsupported media type
              detail: 'The endpoint supports only the application/vnd.api+json Content-Type. This request specified application/json.

                '
    BadCredentials:
      description: Bad credentials.
    Forbidden:
      description: Forbidden.
    MissingResourceId:
      description: Bad request.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - status: 400
              code: parameter_missing
              title: Parameter missing
              detail: The required parameter, id, is missing.
  schemas:
    GetControlAttachmentsResponse:
      type: object
      required:
      - data
      - links
      properties:
        data:
          type: array
          description: The attachments associated with the control.
          items:
            type: object
            description: An attachment associated with a control.
            required:
            - id
            - type
            - attributes
            - relationships
            properties:
              id:
                type: string
                description: The ID of the attachment.
                example: '56'
              type:
                type: string
                description: The classification of the object (`"attachments"`).
                example: attachments
              attributes:
                type: object
                description: The attributes associated with the attachment.
                required:
                - attachment_file_name
                - attachment_content_type
                - attachable_type
                - attachable_id
                - audit_id
                - parent_id
                - download_url
                properties:
                  attachment_file_name:
                    type: string
                    description: The original file name of the attachment.
                    example: report.pdf
                  attachment_content_type:
                    type: string
                    description: The MIME type of the attachment file.
                    example: application/pdf
                  attachable_type:
                    type: string
                    description: The type of resource the attachment is linked to.
                    example: control
                  attachable_id:
                    type: integer
                    description: The ID of the resource the attachment is linked to.
                    example: 456
                  audit_id:
                    type: integer
                    description: The ID of the audit (project) the attachment belongs to.
                    example: 358
                  parent_id:
                    type:
                    - integer
                    - 'null'
                    description: The ID of the parent attachment, if this attachment is a revision or child file. `null` when there is no parent.
                    example: null
                  download_url:
                    type: string
                    description: A signed URL to download the attachment file.
                    example: https://www.example.com/path-to-file/report.pdf
              relationships:
                type: object
                description: The relationships associated with the attachment.
                required:
                - user
                properties:
                  user:
                    type: object
                    description: The user who uploaded the attachment.
                    required:
                    - data
                    properties:
                      data:
                        type: object
                        description: The data associated with the resource.
                        required:
                        - id
                        - type
                        properties:
                          id:
                            type: string
                            description: 'The unique identifier (UID) of the user. For more information on obtaining this value, see

                              <a href="#section/Making-requests">Making requests</a>.

                              '
                            example: yvqdNCtv8TeM47WQtzau
                          type:
                            type: string
                            description: The classification of the object (`"users"`).
                            example: users
        links:
          type: object
          required:
          - next
          - prev
          properties:
            next:
              type:
              - string
              - 'null'
              description: Next page url
              example: /v1/orgs/12345/controls/456/attachments?page[size]=50&page[number]=Mg==
            prev:
              type:
              - string
              - 'null'
              description: Previous page url
              example: null
    Error:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          description: The HTTP status code.
        source:
          type: object
          description: Indicates which part of the request document caused the error.
          required:
          - pointer
          properties:
            pointer:
              type: string
              description: 'A JSON Pointer <a href="https://tools.ietf.org/html/rfc6901" target="_blank">(RFC6901)</a> to the associated entity

                in the request document.

                '
        code:
          type: string
          description: Application-specific error code, expressed as a string value.
        title:
          type: string
          description: A short, human-readable summary of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    GetControlTestAttachmentsResponse:
      type: object
      required:
      - data
      - links
      properties:
        data:
          type: array
          description: The attachments associated with the control test.
          items:
            type: object
            description: An attachment associated with a control test.
            required:
            - id
            - type
            - attributes
            - relationships
            properties:
              id:
                type: string
                description: The ID of the attachment.
                example: '56'
              type:
                type: string
                description: The classification of the object (`"attachments"`).
                example: attachments
              attributes:
                type: object
                description: The attributes associated with the attachment.
                required:
                - attachment_file_name
                - attachment_content_type
                - attachable_type
                - attachable_id
                - audit_id
                - parent_id
                - download_url
                properties:
                  attachment_file_name:
                    type: string
                    description: The original file name of the attachment.
                    example: report.pdf
                  attachment_content_type:
                    type: string
                    description: The MIME type of the attachment file.
                    example: application/pdf
                  attachable_type:
                    type: string
                    description: The type of resource the attachment is linked to.
                    example: control_test
                  attachable_id:
                    type: integer
                    description: The ID of the resource the attachment is linked to.
                    example: 123
                  audit_id:
                    type: integer
                    description: The ID of the audit (project) the attachment belongs to.
                    example: 358
                  parent_id:
                    type:
                    - integer
                    - 'null'
                    description: The ID of the parent attachment, if this attachment is a revision or child file. `null` when there is no parent.
                    example: null
                  download_url:
                    type: string
                    description: A signed URL to download the attachment file.
                    example: https://www.example.com/path-to-file/report.pdf
              relationships:
                type: object
                description: The relationships associated with the attachment.
                required:
                - user
                properties:
                  user:
                    type: object
                    description: The user who uploaded the attachment.
                    required:
                    - data
                    properties:
                      data:
                        type: object
                        description: The data associated with the resource.
                        required:
                        - id
                        - type
                        properties:
                          id:
                            type: string
                            description: 'The unique identifier (UID) of the user. For more information on obtaining this value, see

                              <a href="#section/Making-requests">Making requests</a>.

                              '
                            example: yvqdNCtv8TeM47WQtzau
                          type:
                            type: string
                            description: The classification of the object (`"users"`).
                            example: users
        links:
          type: object
          required:
          - next
          - prev
          properties:
            next:
              type:
              - string
              - 'null'
              description: Next page url
              example: /v1/orgs/12345/control_tests/123/attachments?page[size]=50&page[number]=Mg==
            prev:
              type:
              - string
              - 'null'
              description: Previous page url
              example: null
  parameters:
    attachmentSparseFieldsetParams:
      in: query
      name: fields[attachments]
      description: Requesting the API to return only the specified fields. For more information, see <a href="#section/Making-requests">Making requests</a>
      required: false
      schema:
        type: string
        example: attachment_file_name,attachment_content_type,attachable_type,attachable_id,audit_id,parent_id,download_url,user
    resourceIdParam:
      in: path
      name: id
      description: The ID of the requested resource.
      required: true
      schema:
        type: string
        example: 9999
    pageSizeParam:
      in: query
      name: page[size]
      description: The number of items returned per page. Default is 50. Maximum is 100.
      required: false
      schema:
        type: string
        example: 25
    orgIdParam:
      in: path
      name: org_id
      description: The ID of the HighBond instance.
      required: true
      schema:
        type: string
        example: 1
    pageNumberEncodedParam:
      in: query
      name: page[number]
      description: The Base64-encoded page number of records to return.
      required: false
      schema:
        type: string
        example: Mg==
  securitySchemes:
    bearerToken:
      description: 'HighBond offers the industry-standard OAuth 2.0 flow for connecting to the HighBond platform. OAuth 2.0 provides a

        safe and secure way to access data, while protecting your account credentials.

        '
      type: http
      scheme: bearer
      bearerFormat: oauth2
x-tagGroups:
- name: Core resources
  tags:
  - Robots Agents
  - Robots
  - Robot Tasks
  - Robot Jobs
  - Robot Apps
  - Robot Script Versions
  - Robot Activations
  - Robot Files
  - Robot Working Files
  - Robot Collaborators
  - Robots Folders Collaborators
  - Robot Users
  - Robots Folders
  - Storyboards
  - Collections
  - Questionnaires
  - Analyses
  - Surveys
  - Event Reports
  - Tables
  - Table columns
  - Records
  - Record columns
  - Record statuses
  - Interpretations
  - Metrics
  - Workflow Groups
  - Results Users
  - Results Triggers
  - Project types
  - Custom attributes
  - Request item statuses
  - Projects
  - Projects Admin
  - Planning files
  - Results files
  - Objectives
  - Narratives
  - Risks
  - Controls
  - Control performance schedules
  - Mitigations
  - Control test plans
  - Control tests
  - Attachments
  - Walkthroughs
  - Issues
  - Actions
  - Collaborators
  - Request Items
  - To-dos
  - Sign-offs
  - Entities
  - Scheduler Filters
  - Frameworks
  - Handlers
  - Workflows in Asset Inventory/Asset Manager
  - Asset types
  - Asset record types
  - Attribute types
  - Assets
  - Asset Relationships
  - Asset records
  - Asset Record Relationships
  - Events
  - Template Toolkits
  - Toolkits
  - Roles
  - Role Deletion
  - Compliance Maps
  - Time entries
  - Non-project time categories
  - Timesheets
  - Importer
  - System Users
  - Organizations
  - Impact Reports
  - Activities
  - Users
  - Groups
  - Scheduled Users
  - Scheduled Projects
  - Scheduled Hours
  - Extract
  - Strategy