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


        #### Description


        Retrieves a list of all policies within an organization, including
        details such as policy names, descriptions, and associated frameworks.
      operationId: get-policies
      parameters:
        - name: status
          in: query
          description: Filters policies by the provided object status
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyCollection'
              example:
                - id: d88d505d-5199-11ee-a644-522476618ae8
                  orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                  name: Password Policy
                  description: Password acceptance criteria.
                  ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  effectiveDate: '2025-06-12T18:26:10.0053650+00:00'
                  nextRevisionDate: '2025-06-15T18:26:10.0053650+00:00'
                  nextReviewDate: '2025-06-16T18:26:10.0053650+00:00'
                  policyApprovalStatus: approved
                  effectiveDocumentId: f06fe159-e7c1-4b42-8715-5615ff50b29c
                  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'
                  customFields:
                    - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                      fieldName: Sponsor
                      fieldType: text
                      textValue: John Smith
                  status: active
                  permissions: []
    post:
      summary: Add Policy
      description: >+
        `POST /`


        #### Description


        Creates a new policy within an organization, capturing details such as
        the policy name, description, and associated compliance framework.

      operationId: add-policy
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyPost'
            example:
              name: Password Policy
              description: Password acceptance criteria.
              ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
              customFields:
                - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                  textValue: John Smith
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                name: Password Policy
                description: Password acceptance criteria.
                ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                effectiveDate: '2025-06-12T18:26:10.0053650+00:00'
                nextRevisionDate: '2025-06-15T18:26:10.0053650+00:00'
                nextReviewDate: '2025-06-16T18:26:10.0053650+00:00'
                policyApprovalStatus: approved
                effectiveDocumentId: f06fe159-e7c1-4b42-8715-5615ff50b29c
                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'
                customFields:
                  - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                    fieldName: Sponsor
                    fieldType: text
                    textValue: John Smith
                status: active
                permissions: []
    patch:
      summary: Update Policies
      description: >
        `PATCH /`


        #### Description


        Updates policies within an organization, allowing modifications to their
        names, descriptions, or associated compliance details.
      operationId: patch-policies
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyBulkPatch'
            example:
              policyIds:
                - string
              patch:
                name: Password Policy
                description: Password acceptance criteria.
                ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                customFields:
                  - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                    textValue: John Smith
                status: active
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyCollection'
              example:
                - id: d88d505d-5199-11ee-a644-522476618ae8
                  orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                  name: Password Policy
                  description: Password acceptance criteria.
                  ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  effectiveDate: '2025-06-12T18:26:10.0053650+00:00'
                  nextRevisionDate: '2025-06-15T18:26:10.0053650+00:00'
                  nextReviewDate: '2025-06-16T18:26:10.0053650+00:00'
                  policyApprovalStatus: approved
                  effectiveDocumentId: f06fe159-e7c1-4b42-8715-5615ff50b29c
                  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'
                  customFields:
                    - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                      fieldName: Sponsor
                      fieldType: text
                      textValue: John Smith
                  status: active
                  permissions: []
  /{policyId}:
    get:
      summary: Get Policy
      description: >
        `GET /{policyId}`


        #### Description


        Retrieves a specified policy by its unique ID, including details such as
        policy name, description, and associated frameworks.
      operationId: get-policy
      parameters:
        - name: policyId
          in: path
          description: Unique ID of the policy to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                name: Password Policy
                description: Password acceptance criteria.
                ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                effectiveDate: '2025-06-12T18:26:10.0053650+00:00'
                nextRevisionDate: '2025-06-15T18:26:10.0053650+00:00'
                nextReviewDate: '2025-06-16T18:26:10.0053650+00:00'
                policyApprovalStatus: approved
                effectiveDocumentId: f06fe159-e7c1-4b42-8715-5615ff50b29c
                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'
                customFields:
                  - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                    fieldName: Sponsor
                    fieldType: text
                    textValue: John Smith
                status: active
                permissions: []
    patch:
      summary: Update a single policy
      description: >
        `PATCH /{policyId}`


        #### Description


        Updates an existing policy identified by its ID, allowing modifications
        to its name, description, or associated compliance details.
      operationId: patch-policy
      parameters:
        - name: policyId
          in: path
          description: Unique ID of the policy to patch.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyPatch'
            example:
              name: Password Policy
              description: Password acceptance criteria.
              ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
              customFields:
                - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                  textValue: John Smith
              status: active
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                name: Password Policy
                description: Password acceptance criteria.
                ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                effectiveDate: '2025-06-12T18:26:10.0053650+00:00'
                nextRevisionDate: '2025-06-15T18:26:10.0053650+00:00'
                nextReviewDate: '2025-06-16T18:26:10.0053650+00:00'
                policyApprovalStatus: approved
                effectiveDocumentId: f06fe159-e7c1-4b42-8715-5615ff50b29c
                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'
                customFields:
                  - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                    fieldName: Sponsor
                    fieldType: text
                    textValue: John Smith
                status: active
                permissions: []
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            policy.read: Grants read access to policy
            policy.update: Grants update access to policy
  schemas:
    Policy:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the policy.
        orgId:
          type: string
          format: uuid
          description: The unique identifier of the organization the policy belongs to.
        name:
          type: string
          description: The name of the policy.
        description:
          type: string
          description: The description of the policy.
        ownerId:
          type: string
          format: uuid
          description: The unique identifier of the owner of the policy.
        effectiveDate:
          type: string
          format: date-time
          description: The effective date of the policy (ISO-8601 format).
        nextRevisionDate:
          type: string
          format: date-time
          description: The next revision date for the policy (ISO-8601 format).
        nextReviewDate:
          type: string
          format: date-time
          description: The next review date for the policy (ISO-8601 format).
        policyApprovalStatus:
          $ref: '#/components/schemas/PolicyApprovalStatus'
        effectiveDocumentId:
          type: string
          format: uuid
          description: The unique identifier of the effective document of the policy.
        createdBy:
          type: string
          format: uuid
          description: The unique identifier of the user who created the policy.
        createdOn:
          type: string
          format: date-time
          description: The date and time the policy was created (ISO-8601 format).
        updatedBy:
          type: string
          format: uuid
          description: The unique identifier of the user who last updated the policy.
        updatedOn:
          type: string
          format: date-time
          description: The date and time the policy was last updated (ISO-8601 format).
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValue'
        status:
          $ref: '#/components/schemas/ObjectStatus'
        permissions:
          type: array
          description: The list of permissions for the policy.
          items:
            type: string
      example:
        id: d88d505d-5199-11ee-a644-522476618ae8
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        name: Password Policy
        description: Password acceptance criteria.
        ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        effectiveDate: '2025-06-12T18:26:10.005365Z'
        nextRevisionDate: '2025-06-15T18:26:10.005365Z'
        nextReviewDate: '2025-06-16T18:26:10.005365Z'
        policyApprovalStatus: approved
        effectiveDocumentId: f06fe159-e7c1-4b42-8715-5615ff50b29c
        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'
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            fieldName: Sponsor
            fieldType: text
            textValue: John Smith
        status: active
        permissions: []
    PolicyCollection:
      type: array
      description: A list of policies
      items:
        $ref: '#/components/schemas/Policy'
    PolicyPost:
      type: object
      properties:
        name:
          type: string
          description: The name of the policy.
        description:
          type: string
          description: The description of the policy.
        ownerId:
          type: string
          format: uuid
          description: The unique identifier of the owner of the policy.
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValuePatch'
      required:
        - name
      example:
        name: Password Policy
        description: Password acceptance criteria.
        ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            textValue: John Smith
    PolicyBulkPatch:
      type: object
      properties:
        policyIds:
          type: array
          description: The list of policy identifiers for bulk patching.
          items:
            type: string
            format: uuid
        patch:
          description: The values to bulk update for the policies.
          $ref: '#/components/schemas/PolicyPatch'
      required:
        - policyIds
        - patch
    PolicyPatch:
      type: object
      properties:
        name:
          type: string
          description: The name of the policy.
        description:
          type: string
          description: The description of the policy.
        ownerId:
          type: string
          format: uuid
          description: The unique identifier of the owner of the policy.
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValuePatch'
        status:
          $ref: '#/components/schemas/ObjectStatus'
      example:
        name: Password Policy
        description: Password acceptance criteria.
        ownerId: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            textValue: John Smith
        status: active
    PolicyApprovalStatus:
      type: string
      enum:
        - approved
        - approval
        - changesRequested
        - editing
    CustomFieldObjectValue:
      type: array
      items:
        type: object
        properties:
          fieldId:
            type: string
            description: Unique identifier for the custom field
          fieldName:
            type: string
            description: Name of the custom field
          fieldType:
            type: string
            description: Type of field
            enum:
              - text
              - number
              - date
              - user
              - textSingleSelect
              - textMultiSelect
          numberFormat:
            type: string
            description: Format if the field type is `number`
            enum:
              - decimal
              - percentage
          textValue:
            type: string
            description: Value if the field type is `text`
          numberValue:
            type: number
            description: Value if the field type is `number`
          dateValue:
            type: string
            description: Value if the field type is `date`
          userValue:
            type: string
            description: Value if the field type is `user`
          selection:
            type: string
            description: Value for `textSingleSelect`
          selections:
            type: array
            description: List of values for `textMultiSelect`
            items:
              type: string
    CustomFieldObjectValuePatch:
      type: object
      properties:
        fieldId:
          type: string
          description: Unique identifier for the custom field
        textValue:
          type: string
          description: Value if the field type is `text`
        numberValue:
          type: number
          description: Value if the field type is `number`
        dateValue:
          type: string
          description: Value if the field type is `date`
        userValue:
          type: string
          description: Value if the field type is `user`
        selections:
          type: array
          description: List of values for `textMultiSelect`
          items:
            type: string
    ObjectStatus:
      type: string
      description: The status of the object
      enum:
        - active
        - archived
