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


        #### Description


        Retrieves metadata for a specified organization, control, label, or
        task, providing key contextual and configuration details.
      operationId: get-proof-metadata-collection
      parameters:
        - name: limit
          in: query
          description: The maximum number of proof to return.
          schema:
            maximum: 500
            type: number
            default: 25
        - name: sortBy
          in: query
          description: The proof property to use when sorting the result.
          schema:
            enum:
              - createdBy
              - uploadedOn
            type: string
            default: uploadedOn
        - name: sortDirection
          in: query
          description: The direction the data should be sorted.
          schema:
            enum:
              - asc
              - desc
            type: string
            default: desc
        - name: nextToken
          in: query
          description: Token returned from a previous call to retrieve proof.
          schema:
            type: string
        - name: objectType
          in: query
          description: Linked object type.
          schema:
            enum:
              - control
              - label
            type: string
        - name: objectId
          in: query
          description: Unique ID of the linked object.
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofCollectionResponse'
              example:
                data:
                  - 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'
                nextToken: string
    post:
      summary: Add Proof
      description: >
        `POST /`


        #### Description


        Adds a new proof item to an organization, storing evidence details, file
        attachments, and metadata for compliance tracking.


        **Uploading Testable CSV proof**


        When sending CSV files, you need to explicitly declare the type as
        text/csv. This tells Hyperproof to treat the uploaded blob as tabular
        data. This allows the CSV proof to be usable in automated tests.


        ```bash

        curl --request POST \
          --url https://api.hyperproof.app/v1/proof \
          --header "Authorization: Bearer $ACCESS_TOKEN" \
          --form proof=@"./policies/AcceptableUse.csv:type=text/csv" \
          --form hp-proof-owned-by="$USER_ID"
          --form contentType="text/csv"
        ```
      operationId: add-proof
      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'
  /{proofId}:
    get:
      summary: Get Proof Metadata
      description: >
        `GET {proofId}`


        #### Description


        Retrieves metadata for a specific proof item in an organization by its
        ID, including details such as source, status, and associated objects.
      operationId: get-proof-metadata
      parameters:
        - name: proofId
          in: path
          description: Unique ID of the proof
          required: true
          schema:
            type: string
      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'
    patch:
      summary: Update Proof
      description: >+
        `PATCH /{proofId}`


        #### Description


        Updates an existing proof file identified by its ID, allowing
        modification to whether it is private. Also allows adding the schema
        file for proof uploaded in CSV format to make that file compatible with
        the automated testing feature.


        **Updating Testable CSV proof**


        After uploading a CSV file intended for automated testing, a PATCH
        request should be made to create the schema to be tested.

        The body of the request will define the CSV fields and types for the
        automated testing feature. Available types include text , number ,
        boolean , and date.


        ```bash

        curl --request PATCH 'https://api.hyperproof.app/v1/proof/:proofid' \

        --header 'Content-Type: application/json' \

        --header 'Authorization: ••••••' \

        --data '{
            "isPrivate": false,
            "schema": {
                "class": "CsvFileSchema",
                "fields": [{
                    "name": "Name",
                    "type": "text"
                }, {
                    "name": "Email",
                    "type": "text"
                }]
            }
        }'

        ```

      operationId: update-proof
      parameters:
        - name: proofId
          in: path
          description: Unique identifier of the proof to update.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProofPatch'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proof'
  /{proofId}/versions:
    post:
      summary: Add Proof Version
      description: >
        `POST /{proofId}/versions`


        #### Description


        Creates a new version of an existing proof item, capturing updated
        evidence details, files, or metadata.
      operationId: add-proof-version
      parameters:
        - name: proofId
          in: path
          description: Unique ID of the proof
          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'
  /{proofId}/contents:
    get:
      summary: Gets the contents of a proof.
      description: >
        `GET /{proofId}/contents`


        #### Description


        Retrieves the content of a proof item as a downloadable file, providing
        access to the original evidence data.
      operationId: get-proof-contents
      parameters:
        - name: proofId
          in: path
          description: Unique ID of the proof
          required: true
          schema:
            type: string
        - name: version
          in: query
          description: The proof version to retrieve.
          schema:
            type: number
      responses:
        '200':
          description: Success.
          content:
            '*/*':
              schema:
                type: string
                format: binary
              examples:
                default:
                  value: null
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            proof.read: Grants read access to proofs
            proof.update: Grants update access to proofs
  schemas:
    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'
    ProofCollection:
      type: array
      description: A collection of proof.
      items:
        $ref: '#/components/schemas/Proof'
    ProofCollectionResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ProofCollection'
        nextToken:
          type: string
    ProofPatch:
      type: object
      additionalProperties: false
      properties:
        isPrivate:
          type: boolean
          description: Whether the proof item is private.
        schema:
          $ref: '#/components/schemas/CsvFileSchema'
      example:
        isPrivate: false
        schema:
          class: CsvFileSchema
          fields:
            - name: Name
              type: text
            - name: Email
              type: text
    CsvFileSchema:
      type: object
      description: Schema definition for CSV file proof data.
      required:
        - class
        - fields
      properties:
        class:
          type: string
          description: The schema class type.
          enum:
            - CsvFileSchema
        fields:
          type: array
          description: The field definitions for the schema.
          items:
            type: object
            description: Field definition for tabular data.
            required:
              - name
              - type
            properties:
              name:
                type: string
                description: The case sensitive identifier for the field.
              type:
                type: string
                description: The data type of the field.
                enum:
                  - text
                  - number
                  - boolean
                  - date
              label:
                type: string
                description: The label for the field.
      example:
        class: CsvFileSchema
        fields:
          - name: Name
            type: text
          - name: Access Level
            type: number
          - name: Last Access
            type: date
          - name: MFA Enabled
            type: boolean
