Wegalvanize Collections API

openapi: 3.2.0
info:
  title: HighBond API Reference Collections 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: Collections
  description: 'A collection is a container used to organize analyses that relate to different departments, business processes, or data sets. Collections are the highest level of

    organization in the Results app.


    Your organization can have a maximum of 2,000 collections.


    Learn more about collections.'
paths:
  /orgs/{org_id}/collections:
    get:
      tags:
      - Collections
      operationId: getCollections
      summary: List collections inside an organization
      description: Get a list of all collections
      parameters:
      - $ref: '#/components/parameters/orgIdParam'
      responses:
        '200':
          description: OK.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/MultiCollectionsResponse'
        '400':
          $ref: '#/components/responses/MissingOrgId'
        '401':
          $ref: '#/components/responses/BadCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Collections
      operationId: createCollection
      summary: Create a collection
      description: 'Create a new collection.


        Limitations:

        * Your organization can have a maximum of 2,000 collections.'
      parameters:
      - $ref: '#/components/parameters/orgIdParam'
      requestBody:
        description: The data required to create a collection.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/CreateCollectionPayload'
      responses:
        '201':
          description: Created.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CreateCollectionResponse'
        '400':
          $ref: '#/components/responses/ResourceTypeMismatch'
        '401':
          $ref: '#/components/responses/BadCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/NotJsonapiMediaType'
        '422':
          description: Unprocessable entity.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - status: 422
                  source:
                    pointer: /data/attributes/name
                  code: invalid_resource
                  detail: can't be blank
                - status: 422
                  code: unprocessable_entity
                  detail: Maximum number of 2,000 Collections reached.
  /orgs/{org_id}/collections/{id}:
    get:
      tags:
      - Collections
      operationId: getCollection
      summary: Get a collection
      description: Get information about a collection.
      parameters:
      - $ref: '#/components/parameters/orgIdParam'
      - $ref: '#/components/parameters/resourceIdParam'
      responses:
        '200':
          description: OK.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/SingleCollectionResponse'
        '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'
    put:
      tags:
      - Collections
      operationId: updateCollection
      summary: Update a collection
      description: Make changes to a collection, like renaming it. You do not need to update collections for them to reflect changes in data.
      parameters:
      - $ref: '#/components/parameters/orgIdParam'
      - $ref: '#/components/parameters/resourceIdParam'
      requestBody:
        description: The data required to update a collection.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/UpdateCollectionPayload'
      responses:
        '200':
          description: OK.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/SingleCollectionResponse'
        '400':
          $ref: '#/components/responses/ResourceIdConflict'
        '401':
          $ref: '#/components/responses/BadCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/NotJsonapiMediaType'
        '422':
          description: Unprocessable entity.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - status: 422
                  source:
                    pointer: /data/attributes/name
                  code: invalid_resource
                  detail: is too long (maximum is 255 characters)
    delete:
      tags:
      - Collections
      operationId: deleteCollection
      summary: Delete a collection
      description: 'Permanently delete a collection.


        > **Caution —**

        Deleting a collection also permanently removes all of the analyses and tables associated with the collection.'
      parameters:
      - $ref: '#/components/parameters/orgIdParam'
      - $ref: '#/components/parameters/resourceIdParam'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/MissingOrgId'
        '401':
          $ref: '#/components/responses/BadCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/NotJsonapiMediaType'
  /orgs/{org_id}/collections/{collection_id}/collections_members:
    post:
      tags:
      - Collections
      operationId: postCollectionMember
      summary: Add a user to Results collection member
      description: Add users as a collection member with the predefined Results roles.
      parameters:
      - $ref: '#/components/parameters/orgIdParam'
      - $ref: '#/components/parameters/collectionIdParam'
      requestBody:
        description: The data required to add a member to a collection.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/CollectionMemberRequest'
      responses:
        '200':
          description: OK.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CollectionMemberRequest'
              example:
                data:
                - id: '29'
                  type: collection_members
                  attributes:
                    username: Basil Ryan
                    role: Professional User
                    email: basil@wegalvanize.com
                    admin: false
        '400':
          $ref: '#/components/responses/MissingCollectionId'
        '401':
          $ref: '#/components/responses/BadCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: 'Unprocessable entity.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - status: 422
                  code: unprocessable_entity
                  detail: User is already a member of the specified collection..
  /orgs/{org_id}/collections/{collection_id}/collections_members/{id}:
    patch:
      tags:
      - Collections
      operationId: patchCollectionMember
      summary: Update a user role for a collection
      description: Update the role of an existing collection members to any other predefined Result roles.
      parameters:
      - $ref: '#/components/parameters/orgIdParam'
      - $ref: '#/components/parameters/collectionIdParam'
      - $ref: '#/components/parameters/collectionMemberIdParam'
      requestBody:
        description: The data required to update a member in a collection.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/CollectionMemberRequest'
      responses:
        '200':
          description: OK.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CollectionMemberRequest'
              example:
                data:
                - id: '29'
                  type: collection_members
                  attributes:
                    username: Basil Ryan
                    role: Professional User
                    email: basil@wegalvanize.com
                    admin: false
        '400':
          $ref: '#/components/responses/MissingCollectionId'
        '401':
          $ref: '#/components/responses/BadCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Collections
      operationId: deleteCollectionMember
      summary: Remove a user from the collection
      description: Remove users from the collection members.
      parameters:
      - $ref: '#/components/parameters/orgIdParam'
      - $ref: '#/components/parameters/collectionIdParam'
      - $ref: '#/components/parameters/collectionMemberIdParam'
      responses:
        '204':
          description: No content.
        '400':
          $ref: '#/components/responses/MissingCollectionId'
        '401':
          $ref: '#/components/responses/BadCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    ResourceIdConflict:
      description: Bad request.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - status: 400
              code: resource_id_conflict
              title: Resource ID conflict
              detail: 'The id specified in the request body, 1, conflicts with

                the id specified in the path, 101.

                '
    MissingOrgId:
      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, org_id, is missing.
    BadCredentials:
      description: Bad credentials.
    Forbidden:
      description: Forbidden.
    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.

                '
    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.
    NoContent:
      description: No content.
    MissingCollectionId:
      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, collection_id, is missing.
    ResourceTypeMismatch:
      description: Bad request.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - status: 400
              code: resource_type_mismatch
              title: Resource type mismatch
              detail: 'The requested data type, a-bad-type, is incompatible with the endpoint.

                '
  parameters:
    orgIdParam:
      in: path
      name: org_id
      description: The ID of the HighBond instance.
      required: true
      schema:
        type: string
        example: 1
    collectionIdParam:
      in: path
      name: collection_id
      description: The ID of the collection.
      required: true
      schema:
        type: integer
        example: 1
    resourceIdParam:
      in: path
      name: id
      description: The ID of the requested resource.
      required: true
      schema:
        type: string
        example: 9999
    collectionMemberIdParam:
      in: path
      name: collection_member_id
      description: The ID of the collection member.
      required: true
      schema:
        type: integer
        example: 1
  schemas:
    CollectionMemberRequest:
      type: object
      description: The data required to add a member to a collection.
      required:
      - data
      properties:
        data:
          type: object
          description: The data associated with the resource.
          required:
          - type
          - attributes
          - relationships
          properties:
            type:
              type: string
              description: The classification of the object (`"collection_members"`).
              example: collection_members
            attributes:
              type: object
              description: The attributes associated with the resource.
              required:
              - user_id
              - role
              properties:
                user_id:
                  type: integer
                  description: The ID of the user to add to the collection.
                  example: 123
                role:
                  type: string
                  description: 'Specifies the level of access, or permissions, each member has within individual Collections.


                    **Note:**

                    Organization System Administrators and Results Administrators automatically get a Professional Manager role in all collections.

                    '
                  enum:
                  - Professional Manager
                  - Professional User
                  - Contributor User
                  - Oversight Executive
                  - Oversight Reviewer
                  example: Professional Manager
              example:
                user_id: 123
                role: Professional Manager
    UpdateCollectionPayload:
      type: object
      description: The data associated with the resource.
      required:
      - data
      properties:
        data:
          type: object
          description: The data associated with the resource.
          required:
          - id
          - type
          - attributes
          properties:
            id:
              type: string
              description: The ID of the requested resource.
              example: '1'
            type:
              type: string
              description: The classification of the object (`"collections"`).
              example: collections
            attributes:
              type: object
              description: The attributes associated with the resource.
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the collection.
                  maxLength: 255
                  example: My first Collection
                description:
                  type: string
                  description: The description of the collection.
                  example: Description of My first Collection
                workflow_id:
                  type: integer
                  description: The ID of the workflow associated with the collection.
                  example: 42
    MultiCollectionsResponse:
      type: object
      description: The data associated with the resource.
      required:
      - data
      properties:
        data:
          type: array
          description: The data associated with the resource.
          items:
            type: object
            description: The data associated with the resource.
            required:
            - id
            - type
            - attributes
            properties:
              id:
                type: string
                description: The ID of the requested resource.
                example: '1'
              type:
                type: string
                description: The classification of the object (`"collections"`).
                example: collections
              attributes:
                type: object
                description: The attributes associated with the resource.
                properties:
                  name:
                    type: string
                    description: The name of the collection.
                    maxLength: 255
                    example: My first Collection
                  description:
                    type: string
                    description: The description of the collection.
                    example: Description of My first Collection
                  workflow_id:
                    type: integer
                    description: The ID of the workflow associated with the collection.
                    example: 42
                  default:
                    type: boolean
                    description: Specifies if the collection is a default (system created) collection.
                    example: false
                  archived:
                    type: boolean
                    description: Specifies if the collection is archived (in a read-only state).
                    example: false
                  created_at:
                    type: string
                    description: The date the collection was created.
                    example: '2019-02-09T13:17:26Z'
                    format: date-time
                  updated_at:
                    type: string
                    description: The date the collection was updated.
                    example: '2019-03-18T22:02:05Z'
                    format: date-time
                  collection_type:
                    type: string
                    description: The type of a collection
                    enum:
                    - RegularProject
                    - ProjectsAppIntegrationProject
                    - ReportingProject
                    - ReferenceProject
                    - AssessmentProject
                    example: RegularProject
    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.
    SingleCollectionResponse:
      type: object
      description: The data associated with the resource.
      required:
      - data
      properties:
        data:
          type: object
          description: The data associated with the resource.
          required:
          - id
          - type
          - attributes
          properties:
            id:
              type: string
              description: The ID of the requested resource.
              example: '1'
            type:
              type: string
              description: The classification of the object (`"collections"`).
              example: collections
            attributes:
              type: object
              description: The attributes associated with the resource.
              properties:
                name:
                  type: string
                  description: The name of the collection.
                  maxLength: 255
                  example: My first Collection
                description:
                  type: string
                  description: The description of the collection.
                  example: Description of My first Collection
                workflow_id:
                  type: integer
                  description: The ID of the workflow associated with the collection.
                  example: 42
                default:
                  type: boolean
                  description: Specifies if the collection is a default (system created) collection.
                  example: false
                archived:
                  type: boolean
                  description: Specifies if the collection is archived (in a read-only state).
                  example: false
                created_at:
                  type: string
                  description: The date the collection was created.
                  example: '2019-02-09T13:17:26Z'
                  format: date-time
                updated_at:
                  type: string
                  description: The date the collection was updated.
                  example: '2019-03-18T22:02:05Z'
                  format: date-time
                collection_type:
                  type: string
                  description: The type of a collection
                  enum:
                  - RegularProject
                  - ProjectsAppIntegrationProject
                  - ReportingProject
                  - ReferenceProject
                  - AssessmentProject
                  example: RegularProject
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    CreateCollectionResponse:
      type: object
      description: The data associated with the resource.
      required:
      - data
      properties:
        data:
          type: object
          description: The data associated with the resource.
          required:
          - id
          - type
          - attributes
          properties:
            id:
              type: string
              description: The ID of the requested resource.
              example: '1'
            type:
              type: string
              description: The classification of the object (`"collections"`).
              example: collections
            attributes:
              type: object
              description: The attributes associated with the resource.
              properties:
                name:
                  type: string
                  description: The name of the collection.
                  maxLength: 255
                  example: My first Collection
                description:
                  type: string
                  description: The description of the collection.
                  example: Description of My first Collection
                workflow_id:
                  type: integer
                  description: The ID of the workflow associated with the collection.
                  example: 42
                collection_type:
                  type: string
                  description: The type of a collection
                  enum:
                  - RegularProject
                  - AssessmentProject
                  example: RegularProject
                  default: RegularProject
                default:
                  type: boolean
                  description: Specifies if the collection is a default (system created) collection.
                  example: false
                archived:
                  type: boolean
                  description: Specifies if the collection is archived (in a read-only state).
                  example: false
                created_at:
                  type: string
                  description: The date the collection was created.
                  example: '2019-02-09T13:17:26Z'
                  format: date-time
                updated_at:
                  type: string
                  description: The date the collection was updated.
                  example: '2019-03-18T22:02:05Z'
                  format: date-time
    CreateCollectionPayload:
      type: object
      description: The data associated with the resource.
      required:
      - data
      properties:
        data:
          type: object
          description: The data associated with the resource.
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              description: The classification of the object (`"collections"`).
              example: collections
            attributes:
              type: object
              description: The attributes associated with the resource.
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the collection.
                  maxLength: 255
                  example: My first Collection
                description:
                  type: string
                  description: The description of the collection.
                  example: Description of My first Collection
                workflow_id:
                  type: integer
                  description: The ID of the workflow associated with the collection.
                  example: 42
                collection_type:
                  type: string
                  description: The type of a collection
                  enum:
                  - RegularProject
                  - AssessmentProject
                  example: RegularProject
                  default: RegularProject
  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