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


        #### Description


        Retrieves details of all labels within an organization by their unique
        ID, including their names, descriptions, and associated objects.
      operationId: get-labels
      parameters:
        - name: canLink
          in: query
          description: >-
            If true, only returns labels to which the requesting user has link
            permission
          schema:
            type: string
        - name: status
          in: query
          description: Filters resultsby the provided object status
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelCollection'
              example:
                - id: d88d505d-5199-11ee-a644-522476618ae8
                  orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                  name: Acceptable use of assets
                  description: List of acceptable uses of assets by company employees.
                  freshnessPolicy: manual
                  freshForDuration: PT720H
                  freshness: fresh
                  freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
                  freshAsOfNote: Initial freshness set
                  expiration: '2025-02-11T06:26:10.0000000+00:00'
                  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 Label
      description: >+
        `POST /`


        #### Description


        Creates a new label within an organization, defining its name,
        description, and associated properties for categorizing objects.

      operationId: add-label
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelPost'
            example:
              name: Acceptable use of assets
              description: List of acceptable uses of assets by company employees.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                name: Acceptable use of assets
                description: List of acceptable uses of assets by company employees.
                freshnessPolicy: manual
                freshForDuration: PT720H
                freshness: fresh
                freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
                freshAsOfNote: Initial freshness set
                expiration: '2025-02-11T06:26:10.0000000+00:00'
                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: []
  /summaries:
    get:
      summary: Get Label Summaries
      description: >
        `GET /labels/summaries`


        #### Description


        Retrieves summaries of all labels within an organization, including key
        details such as label names, descriptions, and usage counts.
      operationId: get-label-summaries
      parameters:
        - name: canLink
          in: query
          description: >-
            If true, only returns labels the requesting user has link permission
            for
          schema:
            type: string
        - 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/LabelSummaryCollection'
              example:
                - id: 09bb0a00-519a-11ee-a644-522476618ae8
                  name: Acceptable use of assets
                  createdOn: '2023-09-08T18:26:10.0053650+00:00'
                  updatedOn: '2023-09-08T18:26:10.0053650+00:00'
                  permissions: []
  /{labelId}:
    get:
      summary: Get Label
      description: >
        `GET /{labelId}`


        #### Description


        Retrieves details of a specific label by its unique ID, including its
        name, description, and associated objects.
      operationId: get-label
      parameters:
        - name: labelId
          in: path
          description: Unique iD of the label to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                name: Acceptable use of assets
                description: List of acceptable uses of assets by company employees.
                freshnessPolicy: manual
                freshForDuration: PT720H
                freshness: fresh
                freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
                freshAsOfNote: Initial freshness set
                expiration: '2025-02-11T06:26:10.0000000+00:00'
                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 Label
      description: >
        `PATCH /{labelId}`


        #### Description


        Updates an existing label identified by its ID, allowing changes to its
        name, description, or associated metadata.
      operationId: update-label
      parameters:
        - name: labelId
          in: path
          description: Unique ID of the label to update.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelPatch'
            example:
              name: Acceptable use of assets
              description: List of acceptable uses of assets by company employees.
              freshnessPolicy: manual
              freshForDuration: PT720H
              freshness: fresh
              freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
              freshAsOfNote: Updating expired label freshness
              customFields:
                - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                  value: Antonio Moreno
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                name: Acceptable use of assets
                description: List of acceptable uses of assets by company employees.
                freshnessPolicy: manual
                freshForDuration: PT720H
                freshness: fresh
                freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
                freshAsOfNote: Initial freshness set
                expiration: '2025-02-11T06:26:10.0000000+00:00'
                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: []
  /{labelId}/proof:
    post:
      summary: Add Label Proof
      description: >
        `POST /{labelId}/proof`


        #### Description


        Adds a proof item to a specified label, associating the evidence with
        that label for easier organization and tracking.
      operationId: add-label-proof
      parameters:
        - name: labelId
          in: path
          description: Unique ID of the label.
          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:
            label.read: Grants read access to labels
            label.update: Grants update access to labels
  schemas:
    Label:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the label.
        orgId:
          type: string
          description: The unique identifier for the organization the label belongs to.
        name:
          type: string
          description: The name of the label.
        description:
          type: string
          description: The description of the label.
        freshnessPolicy:
          $ref: '#/components/schemas/FreshnessPolicy'
        freshForDuration:
          type: string
          description: The duration after which label becomes stale.
        freshness:
          $ref: '#/components/schemas/Freshness'
        freshAsOfDate:
          type: string
          description: The date when the label was last marked 'fresh' (ISO-8601 format).
        freshAsOfNote:
          type: string
          description: The note populated when the label was marked 'fresh'.
        createdBy:
          type: string
          description: The unique identifier of the user who created the label.
        createdOn:
          type: string
          description: The date and time the label was created (ISO-8601 format).
        updatedBy:
          type: string
          description: The unique identifier of the user who last updated the label.
        updatedOn:
          type: string
          description: The date and time the label was last updated (ISO-8601 format).
        customFields:
          type: array
          description: The custom fields for the label.
          items:
            $ref: '#/components/schemas/CustomFieldObjectValue'
        status:
          $ref: '#/components/schemas/ObjectStatus'
        permissions:
          type: array
          description: The list of permissions for the label.
          items:
            type: string
        _isPartialData:
          type: boolean
          description: >-
            This is true when the user does not have read permissions on the
            label.
      example:
        id: d88d505d-5199-11ee-a644-522476618ae8
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        name: Acceptable use of assets
        description: List of acceptable uses of assets by company employees.
        freshnessPolicy: manual
        freshForDuration: PT720H
        freshness: fresh
        freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
        freshAsOfNote: Initial freshness set
        expiration: '2025-02-11T18:26:10.005365Z'
        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: []
    LabelCollection:
      type: array
      description: A collection of labels.
      items:
        $ref: '#/components/schemas/Label'
    LabelPost:
      type: object
      properties:
        name:
          type: string
          description: The name of the label.
        description:
          type: string
          description: The description of the label.
      required:
        - name
      example:
        name: Acceptable use of assets
        description: List of acceptable uses of assets by company employees.
    LabelPatch:
      type: object
      properties:
        name:
          type: string
          description: The name of the label.
        description:
          type: string
          description: The description of the label.
        freshnessPolicy:
          $ref: '#/components/schemas/FreshnessPolicy'
        freshForDuration:
          type: string
          description: >-
            Sets the duration after which the label becomes stale. Supply as a
            string in standard ISO-8601 duration format ex: P1Y3M2D or PT720H
        freshness:
          $ref: '#/components/schemas/Freshness'
        freshAsOfDate:
          type: string
          description: Sets the date and time when the label was last fresh.
        freshAsOfNote:
          type: string
          description: >-
            Adds a note when setting freshness. Cannot be set without also
            updating freshAsOfDate
        resetFreshnessNote:
          type: string
          description: >-
            Adds a note for resetting a label's freshness with an existing
            freshness policy.
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValuePatch'
        status:
          $ref: '#/components/schemas/ObjectStatus'
      example:
        name: Acceptable use of assets
        description: List of acceptable uses of assets by company employees.
        freshnessPolicy: manual
        freshForDuration: PT720H
        freshness: fresh
        freshAsOfDate: 2025-01-12T18:26:10.00.5365Z
        freshAsOfNote: Updating expired label freshness
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            value: Antonio Moreno
    LabelSummaryCollection:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
          name:
            type: string
          createdOn:
            type: string
          updatedOn:
            type: string
          permissions:
            type: array
            items:
              type: string
      example:
        - id: 09bb0a00-519a-11ee-a644-522476618ae8
          name: Acceptable use of assets
          createdOn: '2023-09-08T18:26:10.005365Z'
          updatedOn: '2023-09-08T18:26:10.005365Z'
          permissions: []
    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'
    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
    Freshness:
      type: string
      description: >-
        The freshness status of an object. Cannot be set if 'freshnessPolicy' is
        'none' and 'freshAsOfDate' is null.
      enum:
        - noFreshness
        - fresh
        - expired
        - unknown
    FreshnessPolicy:
      type: string
      description: >-
        The freshness policy of an object. Set to 'manual' with a
        'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.
      enum:
        - none
        - manual
