openapi: 3.0.1
info:
  title: Programs API
  description: Provides access to the programs that are part of a Hyperproof organization.
  version: '1.0'
servers:
  - url: https://api.hyperproof.app/v1/programs
    description: Hyperproof US
  - url: https://api.hyperproofgov.app/v1/programs
    description: Hyperproof Gov
  - url: https://api.hyperproof.eu/v1/programs
    description: Hyperproof EU
security:
  - oauth2: []
paths:
  /:
    get:
      summary: Get Programs
      description: >+
        `GET /`


        #### Description


        Retrieves details of all programs within an organization, including
        their names, descriptions, statuses, and associated frameworks or
        controls.

      operationId: get-programs
      parameters:
        - name: status
          in: query
          description: Filters results by the provided object status
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgramCollection'
              example:
                - name: string
                  sectionRootId: string
                  primaryContactId: string
                  workStatus: operating
    post:
      summary: Add Program
      description: >
        `POST /`


        #### Description


        Creates a new program within an organization, defining its name,
        description, and associated compliance frameworks or objectives.
      operationId: add-program
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProgramPost'
            example:
              desription: string
              name: string
              sectionRootId: string
              sourceTemplateId: string
              primaryContactId: string
              workStatus: defining
              selectedBaselines:
                - low
              jumpstartProgramIds:
                - string
              cloneProgramName: string
              frameworkLicenseNotice: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Program'
              example:
                name: string
                sectionRootId: string
                primaryContactId: string
                workStatus: operating
  /{programId}:
    get:
      summary: Get a Program
      description: >
        `GET /{programId}`


        #### Description


        Fetches detailed information about a specific Program using its unique
        ID.
      operationId: get-programid
      parameters:
        - name: programId
          in: path
          description: Unique ID of the program.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Program'
              example:
                name: string
                sectionRootId: string
                primaryContactId: string
                workStatus: operating
    patch:
      summary: Update a Program
      description: >
        `PATCH /{programId}`


        #### Description


        Updates an existing program identified by its ID, allowing changes to
        its name, description, or associated compliance details.
      operationId: patch-programid
      parameters:
        - name: programId
          in: path
          description: Unique ID of the program.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProgramPatch'
            example:
              name: string
              description: string
              workStatus: defining
              overrideHealth: true
              overrideHealthHealth: critical
              overrideHealthBy: string
              overrideHealthReason: string
              selectedBaselines:
                - low
              baselineEnabled: true
              frameworkVersionMappingId: string
              removedRequirementIds:
                - string
              updatedRequirementIds:
                - string
              cloneProgramName: string
              isUpdateComplete: true
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Program'
              example:
                name: string
                sectionRootId: string
                primaryContactId: string
                workStatus: operating
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            program.read: Grants read access to programs
            program.update: Grants update access to programs
  schemas:
    Program:
      type: object
      required:
        - name
        - sectionRootId
        - primaryContactId
        - workStatus
      properties:
        id:
          type: string
          description: The unique identifier for the program
        name:
          type: string
          description: The name of the program
        description:
          type: string
          description: The description of the program
        sectionRootId:
          type: string
          description: The unique identifier for the section root
        programLogoName:
          type: string
          description: The name of the program logo
        sourceTemplateId:
          type: string
          description: The unique identifier of the source template
        sourceFrameworkId:
          type: string
          description: The unique identifier of the source framework
        sourceFramework:
          type: string
          description: The source framework
        primaryContactId:
          type: string
          description: The unique identifier of the primary contact
        workStatus:
          $ref: '#/components/schemas/ProgramWorkStatus'
        overrideHealth:
          type: boolean
          description: Whether health status is overridden
        overrideHealthHealth:
          $ref: '#/components/schemas/Health'
        overrideHealthById:
          type: string
          description: The unique identifier of the user who overrode the health status
        overrideHealthOn:
          type: string
          description: The date when health was overridden (ISO-8601 format)
        overrideHealthReason:
          type: string
          description: The reason for overriding health status
        selectedBaselines:
          type: array
          items:
            $ref: '#/components/schemas/BaselineType'
        baselineEnabled:
          type: boolean
          description: Whether baseline is enabled for the program
        isUpdating:
          type: boolean
          description: Whether the program is currently being updated
        updateAvailable:
          type: boolean
          description: Whether an update is available for the program
        frameworkVersionMapping:
          type: object
          description: Mapping details for framework versions
          properties:
            sourceVersion:
              type: string
              description: The source version of the framework
            targetVersion:
              type: string
              description: The target version of the framework
            summary:
              type: string
              description: Summary of the version mapping
            name:
              type: string
              description: The name of the version mapping
            orgId:
              type: string
              description: The unique identifier of the organization
            allOrgsAllowed:
              type: boolean
              description: Whether all organizations are allowed
            allowedOrgIds:
              type: array
              items:
                type: string
                description: List of allowed organization identifiers
        clonedProgramId:
          type: string
          description: Unique identifier of the cloned program, if applicable
        frameworkLicenseNotice:
          type: string
          description: License notice for the framework
        frameworkVersionMappingId:
          type: string
          description: Unique identifier for the framework version mapping
      example:
        name: string
        sectionRootId: string
        primaryContactId: string
        workStatus: operating
    ProgramCollection:
      type: array
      items:
        $ref: '#/components/schemas/Program'
    ProgramPost:
      type: object
      required:
        - description
        - name
        - sectionRootId
        - primaryContact
        - workStatus
      properties:
        desription:
          type: string
          description: The description of the program
        name:
          type: string
          description: The name of the Program
        sectionRootId:
          type: string
          description: The unique identifier for the section root
        sourceTemplateId:
          type: string
          description: The unique identifier of the source template
        primaryContactId:
          type: string
          description: The unique identifier of the primary contact
        workStatus:
          $ref: '#/components/schemas/ProgramWorkStatus'
        selectedBaselines:
          type: array
          items:
            $ref: '#/components/schemas/BaselineType'
        jumpstartProgramIds:
          type: array
          description: List of jumpstart program unique identifiers
          items:
            type: string
        cloneProgramName:
          type: string
          description: Name of the program to clone, if applicable
        frameworkLicenseNotice:
          type: string
          description: License notice for the framework
    ProgramPatch:
      type: object
      properties:
        name:
          type: string
          description: The name of the Program
        description:
          type: string
          description: The description of the program
        workStatus:
          $ref: '#/components/schemas/ProgramWorkStatus'
        overrideHealth:
          type: boolean
          description: >-
            Whether health status is overridden.  If true,
            'overrideHealthHealth', 'overrideHealthBy', and
            'overrideHealthReason' must be populated
        overrideHealthHealth:
          $ref: '#/components/schemas/Health'
        overrideHealthBy:
          type: string
          description: The unique identifier of the user who overrode the health status
        overrideHealthReason:
          type: string
          description: The reason for overriding health status
        selectedBaselines:
          type: array
          items:
            $ref: '#/components/schemas/BaselineType'
        baselineEnabled:
          type: boolean
          description: Whether baseline is enabled for the program
        frameworkVersionMappingId:
          type: string
          description: The unique identifier for the framework version mapping
        removedRequirementIds:
          type: array
          description: List of requirement IDs that have been removed
          items:
            type: string
        updatedRequirementIds:
          type: array
          description: List of requirement IDs that have been updated
          items:
            type: string
        cloneProgramName:
          type: string
          description: The name of the program to clone, if applicable
        isUpdateComplete:
          type: boolean
          description: Whether the program update is complete
    BaselineType:
      type: string
      description: Program baseline type if applicable to your program.
      enum:
        - low
        - moderate
        - high
        - level1
        - level2
        - level3
        - level4
        - level5
        - privacy
        - security
        - availability
        - confidentiality
        - processingIntegrity
    Health:
      type: string
      description: Health status
      enum:
        - critical
        - atRisk
        - healthy
        - notAvailable
    ProgramWorkStatus:
      type: string
      description: Program work status
      enum:
        - defining
        - operating
