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


        #### Description


        Retrieves details of all policy versions linked to a specific policy,
        including version metadata, content, and associated documents or proof.
      operationId: get-policy-versions
      parameters:
        - name: policyId
          in: query
          description: Gets policy versions by this policy ID.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyVersionCollection'
              example:
                - id: d88d505d-5199-11ee-a644-522476618ae8
                  orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                  policyId: '85604927-8912-4471-8db6-480571dc78ce '
                  documentId: cf0bedbe-6ecd-46b1-a84e-07018f61c2aa
                  name: Password Policy Version
                  ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  revisionStatus: approval
                  revisionStatusUpdatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  revisionStatusUpdatedOn: '2025-06-15T18:26:10.0053650+00:00'
                  nextRevisionDate: '2025-06-15T18:26:10.0053650+00:00'
                  nextReviewDate: '2025-06-16T18:26:10.0053650+00:00'
                  approvedDate: '2025-06-15T18:26:10.0053650+00:00'
                  retiredDate: '2025-06-15T18:26:10.0053650+00:00'
                  effectiveDate: '2025-06-12T18:26:10.0053650+00:00'
                  publishedUrl: www.hyperproof.io
                  shareLink: www.hyperproof.io
                  createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  createdOn: '2025-01-12T18:26:10.0053650+00:00'
                  updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  updatedOn: '2025-01-12T18:26:10.0053650+00:00'
                  status: active
                  permissions: []
    post:
      summary: Add Policy Version
      description: >
        `POST /{policyId}`


        #### Description


        Creates a new version of an existing policy identified by its ID,
        capturing updated content, metadata, or compliance references.
      operationId: add-policy-version
      parameters:
        - name: policyId
          in: query
          description: Gets policy versions by this policy ID.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyVersionPost'
            example:
              name: Password Policy Version
              revisionStatus: approval
              nextRevisionDate: '2025-06-15T18:26:10.0053650+00:00'
              nextReviewDate: '2025-06-16T18:26:10.0053650+00:00'
              approvedDate: '2025-06-15T18:26:10.0053650+00:00'
              retiredDate: '2025-06-15T18:26:10.0053650+00:00'
              effectiveDate: '2025-06-12T18:26:10.0053650+00:00'
              publishedUrl: www.google.com
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyVersion'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                policyId: '85604927-8912-4471-8db6-480571dc78ce '
                documentId: cf0bedbe-6ecd-46b1-a84e-07018f61c2aa
                name: Password Policy Version
                ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                revisionStatus: approval
                revisionStatusUpdatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                revisionStatusUpdatedOn: '2025-06-15T18:26:10.0053650+00:00'
                nextRevisionDate: '2025-06-15T18:26:10.0053650+00:00'
                nextReviewDate: '2025-06-16T18:26:10.0053650+00:00'
                approvedDate: '2025-06-15T18:26:10.0053650+00:00'
                retiredDate: '2025-06-15T18:26:10.0053650+00:00'
                effectiveDate: '2025-06-12T18:26:10.0053650+00:00'
                publishedUrl: www.hyperproof.io
                shareLink: www.hyperproof.io
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2025-01-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2025-01-12T18:26:10.0053650+00:00'
                status: active
                permissions: []
  /{versionId}:
    get:
      summary: Get Policy Version
      description: >
        `GET /{versionId}`


        #### Description


        Retrieves details of a specific policy version by its unique ID,
        including version metadata, content, and associated documents or proof.
      operationId: get-policy-version
      parameters:
        - name: versionId
          in: path
          description: Unique ID of the policy version.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyVersion'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                policyId: '85604927-8912-4471-8db6-480571dc78ce '
                documentId: cf0bedbe-6ecd-46b1-a84e-07018f61c2aa
                name: Password Policy Version
                ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                revisionStatus: approval
                revisionStatusUpdatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                revisionStatusUpdatedOn: '2025-06-15T18:26:10.0053650+00:00'
                nextRevisionDate: '2025-06-15T18:26:10.0053650+00:00'
                nextReviewDate: '2025-06-16T18:26:10.0053650+00:00'
                approvedDate: '2025-06-15T18:26:10.0053650+00:00'
                retiredDate: '2025-06-15T18:26:10.0053650+00:00'
                effectiveDate: '2025-06-12T18:26:10.0053650+00:00'
                publishedUrl: www.hyperproof.io
                shareLink: www.hyperproof.io
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2025-01-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2025-01-12T18:26:10.0053650+00:00'
                status: active
                permissions: []
    patch:
      summary: Update a single policy version
      description: >
        `PATCH /{versionId}?policyId={policyId}`


        #### Description


        Updates an existing policy version, allowing modifications to its
        content, metadata, or associated references.
      operationId: patch-policy-version
      parameters:
        - name: versionId
          in: path
          description: Unique ID of the policy version.
          required: true
          schema:
            type: string
        - name: policyId
          in: query
          description: Gets policy versions by this policy ID.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyVersionPatch'
            example:
              name: Password Policy Version
              revisionStatus: approval
              status: active
              nextRevisionDate: '2025-06-15T18:26:10.0053650+00:00'
              nextReviewDate: '2025-06-16T18:26:10.0053650+00:00'
              approvedDate: '2025-06-15T18:26:10.0053650+00:00'
              retiredDate: '2025-06-15T18:26:10.0053650+00:00'
              effectiveDate: '2025-06-12T18:26:10.0053650+00:00'
              publishedUrl: www.google.com
              shareLink: www.google.com
              ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
              clearNextReviewDate: false
              clearNextRevisionDate: false
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyVersion'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                policyId: '85604927-8912-4471-8db6-480571dc78ce '
                documentId: cf0bedbe-6ecd-46b1-a84e-07018f61c2aa
                name: Password Policy Version
                ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                revisionStatus: approval
                revisionStatusUpdatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                revisionStatusUpdatedOn: '2025-06-15T18:26:10.0053650+00:00'
                nextRevisionDate: '2025-06-15T18:26:10.0053650+00:00'
                nextReviewDate: '2025-06-16T18:26:10.0053650+00:00'
                approvedDate: '2025-06-15T18:26:10.0053650+00:00'
                retiredDate: '2025-06-15T18:26:10.0053650+00:00'
                effectiveDate: '2025-06-12T18:26:10.0053650+00:00'
                publishedUrl: www.hyperproof.io
                shareLink: www.hyperproof.io
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2025-01-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2025-01-12T18:26:10.0053650+00:00'
                status: active
                permissions: []
  /{versionId}/proof:
    post:
      summary: Add Policy Version Proof
      description: >
        `POST /{versionId}/proof?policyId={policyId}`


        #### Description


        Adds a proof item to a specific policy version, linking evidence or
        supporting documentation to demonstrate compliance.
      operationId: add-policy-version-proof
      parameters:
        - name: versionId
          in: path
          description: Unique ID of the policy version.
          required: true
          schema:
            type: string
        - name: policyId
          in: query
          description: Unique ID of the policy version's parent policy.
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data: {}
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proof'
              example:
                id: 4eb909de-51af-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                filename: example.txt
                contentType: text/plain
                fileExtension: txt
                size: 627
                version: 0
                source: localComputer
                ownedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                uploadedOn: '2023-09-12T20:59:47.6943530+00:00'
                isPrivate: false
                status: active
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2023-09-12T20:59:47.6943530+00:00'
                updatedOn: '2023-09-12T20:59:47.6943530+00:00'
  /{versionId}/documents:
    post:
      summary: Add a Policy Version Document
      description: >
        `POST /{versionId}/documents?policyId={policyId}`


        #### Description


        Adds a source document to a specific policy version, linking supporting
        evidence or reference materials to that version.
      operationId: add-policy-document
      parameters:
        - name: versionId
          in: path
          description: Unique ID of the policy version.
          required: true
          schema:
            type: string
        - name: policyId
          in: query
          description: Unique ID of the policy version's parent policy.
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data: {}
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proof'
              example:
                id: 4eb909de-51af-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                filename: example.txt
                contentType: text/plain
                fileExtension: txt
                size: 627
                version: 0
                source: localComputer
                ownedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                uploadedOn: '2023-09-12T20:59:47.6943530+00:00'
                isPrivate: false
                status: active
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2023-09-12T20:59:47.6943530+00:00'
                updatedOn: '2023-09-12T20:59:47.6943530+00:00'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            policyversion.read: Grants read access to policy versions
            policyversion.update: Grants update access to policy versions
  schemas:
    PolicyVersion:
      type: object
      properties:
        id:
          type: string
        orgId:
          type: string
        policyId:
          type: string
        documentId:
          type: string
        name:
          type: string
        ownerId:
          type: string
        revisionStatus:
          $ref: '#/components/schemas/PolicyVersionStatus'
        revisionStatusUpdatedBy:
          type: string
        revisionStatusUpdatedOn:
          type: string
        nextRevisionDate:
          type: string
        nextReviewDate:
          type: string
        approvedDate:
          type: string
        retiredDate:
          type: string
        effectiveDate:
          type: string
        publishedUrl:
          type: string
        shareLink:
          type: string
        createdBy:
          type: string
        createdOn:
          type: string
        updatedBy:
          type: string
        updatedOn:
          type: string
        status:
          $ref: '#/components/schemas/ObjectStatus'
        permissions:
          type: array
          items:
            type: string
      example:
        id: d88d505d-5199-11ee-a644-522476618ae8
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        policyId: '85604927-8912-4471-8db6-480571dc78ce '
        documentId: cf0bedbe-6ecd-46b1-a84e-07018f61c2aa
        name: Password Policy Version
        ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        revisionStatus: approval
        revisionStatusUpdatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        revisionStatusUpdatedOn: '2025-06-15T18:26:10.005365Z'
        nextRevisionDate: '2025-06-15T18:26:10.005365Z'
        nextReviewDate: '2025-06-16T18:26:10.005365Z'
        approvedDate: '2025-06-15T18:26:10.005365Z'
        retiredDate: '2025-06-15T18:26:10.005365Z'
        effectiveDate: '2025-06-12T18:26:10.005365Z'
        publishedUrl: www.hyperproof.io
        shareLink: www.hyperproof.io
        createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        createdOn: '2025-01-12T18:26:10.005365Z'
        updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        updatedOn: '2025-01-12T18:26:10.005365Z'
        status: active
        permissions: []
    PolicyVersionCollection:
      type: array
      items:
        $ref: '#/components/schemas/PolicyVersion'
    PolicyVersionPost:
      type: object
      properties:
        name:
          type: string
        revisionStatus:
          $ref: '#/components/schemas/PolicyVersionStatus'
        nextRevisionDate:
          type: string
        nextReviewDate:
          type: string
        approvedDate:
          type: string
        retiredDate:
          type: string
        effectiveDate:
          type: string
        publishedUrl:
          type: string
      required:
        - name
        - revisionStatus
      example:
        name: Password Policy Version
        revisionStatus: approval
        nextRevisionDate: '2025-06-15T18:26:10.005365Z'
        nextReviewDate: '2025-06-16T18:26:10.005365Z'
        approvedDate: '2025-06-15T18:26:10.005365Z'
        retiredDate: '2025-06-15T18:26:10.005365Z'
        effectiveDate: '2025-06-12T18:26:10.005365Z'
        publishedUrl: www.google.com
    PolicyVersionPatch:
      type: object
      properties:
        name:
          type: string
        revisionStatus:
          $ref: '#/components/schemas/PolicyVersionStatus'
        status:
          $ref: '#/components/schemas/ObjectStatus'
        nextRevisionDate:
          type: string
        nextReviewDate:
          type: string
        approvedDate:
          type: string
        retiredDate:
          type: string
        effectiveDate:
          type: string
        publishedUrl:
          type: string
        shareLink:
          type: string
        ownerId:
          type: string
        clearNextReviewDate:
          type: boolean
        clearNextRevisionDate:
          type: boolean
      example:
        name: Password Policy Version
        revisionStatus: approval
        status: active
        nextRevisionDate: '2025-06-15T18:26:10.005365Z'
        nextReviewDate: '2025-06-16T18:26:10.005365Z'
        approvedDate: '2025-06-15T18:26:10.005365Z'
        retiredDate: '2025-06-15T18:26:10.005365Z'
        effectiveDate: '2025-06-12T18:26:10.005365Z'
        publishedUrl: www.google.com
        shareLink: www.google.com
        ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        clearNextReviewDate: false
        clearNextRevisionDate: false
    PolicyVersionStatus:
      type: string
      enum:
        - approval
        - draft
        - effective
        - retired
    ObjectStatus:
      type: string
      description: The status of the object
      enum:
        - active
        - archived
    Proof:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the proof item
        orgId:
          type: string
          description: Unique identifier for the organization
        filename:
          type: string
          description: Name of the uploaded file
        nameOverride:
          type: string
          description: Name of proof Hyperproof given by Hyperproof user
        contentType:
          type: string
          description: MIME type of the file (e.g.,`text/plain`)
        fileExtension:
          type: string
          description: File extension (e.g.,`txt`)
        size:
          type: number
          description: File size in bytes
        version:
          type: integer
          description: Version of the proof item
        source:
          type: string
          description: Source of the file (e.g.,localComputer)
        sourceVersion:
          type: integer
          description: The version of the proof maintained by the source system
        ownedBy:
          type: string
          description: Unique identifier of the user who owns the proof item
        isPrivate:
          type: boolean
          description: Whether the proof item is private
        uploadedOn:
          type: string
          description: The date the proof was uploaded (ISO-8601 format)
        status:
          type: string
          description: Status of the proof item
          enum:
            - active
            - archived
            - deleted
            - pending
            - canceled
        createdBy:
          type: string
          description: Unique identifier of the user who created the proof item
        createdOn:
          type: string
          description: The date the proof was created (ISO-8601 format)
        updatedBy:
          type: string
          description: Unique identifier of the user who last updated the proof item
        updatedOn:
          type: string
          description: The date the proof was updated (ISO-8601 format)
      example:
        id: 4eb909de-51af-11ee-a644-522476618ae8
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        filename: example.txt
        contentType: text/plain
        fileExtension: txt
        size: 627
        version: 0
        source: localComputer
        ownedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        uploadedOn: '2023-09-12T20:59:47.694353Z'
        isPrivate: false
        status: active
        createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        createdOn: '2023-09-12T20:59:47.694353Z'
        updatedOn: '2023-09-12T20:59:47.694353Z'
