Skip to content
Hyperproof API
/
/
Labels API

Labels API (1.0)

Provides access to the labels that are part of a Hyperproof organization.

Download OpenAPI description
labels.openapi.json
labels.openapi.yaml
Languages
Servers
Mock server
https://developer.hyperproof.app/_mock/hyperproof-api/labels/labels.openapi
Hyperproof US
https://api.hyperproof.app/v1/labels
Hyperproof Gov
https://api.hyperproofgov.app/v1/labels
Hyperproof EU
https://api.hyperproof.eu/v1/labels

Get Labels

Request

GET /

Description

Retrieves details of all labels within an organization by their unique ID, including their names, descriptions, and associated objects.

Security
oauth2
Query
canLinkstring

If true, only returns labels to which the requesting user has link permission

statusstring

Filters resultsby the provided object status

curl -i -X GET \
  'https://developer.hyperproof.app/_mock/hyperproof-api/labels/labels.openapi/?canLink=string&status=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success.

Bodyapplication/jsonArray [
idstring

The unique identifier of the label.

Example: "d88d505d-5199-11ee-a644-522476618ae8"
orgIdstring

The unique identifier for the organization the label belongs to.

Example: "ce83e3cd-5199-11ee-a644-522476618ae8"
namestring

The name of the label.

Example: "Acceptable use of assets"
descriptionstring

The description of the label.

Example: "List of acceptable uses of assets by company employees."
freshnessPolicystring(FreshnessPolicy)

The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.

Enum"none""manual"
freshForDurationstring

The duration after which label becomes stale.

Example: "PT720H"
freshnessstring(Freshness)

The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.

Enum"noFreshness""fresh""expired""unknown"
freshAsOfDatestring

The date when the label was last marked 'fresh' (ISO-8601 format).

Example: "2025-01-12T18:26:10.00.5365Z"
freshAsOfNotestring

The note populated when the label was marked 'fresh'.

Example: "Initial freshness set"
createdBystring

The unique identifier of the user who created the label.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date and time the label was created (ISO-8601 format).

Example: "2025-01-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the label.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date and time the label was last updated (ISO-8601 format).

Example: "2025-01-12T18:26:10.005365Z"
customFieldsArray of objects(CustomFieldObjectValue)

The custom fields for the label.

statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
permissionsArray of strings

The list of permissions for the label.

Example: []
_isPartialDataboolean

This is true when the user does not have read permissions on the label.

]
Response
application/json
[
  {
    "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": []
  }
]

Add Label

Request

POST /

Description

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

Security
oauth2
Bodyapplication/json
namestringrequired

The name of the label.

Example: "Acceptable use of assets"
descriptionstring

The description of the label.

Example: "List of acceptable uses of assets by company employees."
curl -i -X POST \
  https://developer.hyperproof.app/_mock/hyperproof-api/labels/labels.openapi/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acceptable use of assets",
    "description": "List of acceptable uses of assets by company employees."
  }'

Responses

Success.

Bodyapplication/json
idstring

The unique identifier of the label.

Example: "d88d505d-5199-11ee-a644-522476618ae8"
orgIdstring

The unique identifier for the organization the label belongs to.

Example: "ce83e3cd-5199-11ee-a644-522476618ae8"
namestring

The name of the label.

Example: "Acceptable use of assets"
descriptionstring

The description of the label.

Example: "List of acceptable uses of assets by company employees."
freshnessPolicystring(FreshnessPolicy)

The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.

Enum"none""manual"
freshForDurationstring

The duration after which label becomes stale.

Example: "PT720H"
freshnessstring(Freshness)

The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.

Enum"noFreshness""fresh""expired""unknown"
freshAsOfDatestring

The date when the label was last marked 'fresh' (ISO-8601 format).

Example: "2025-01-12T18:26:10.00.5365Z"
freshAsOfNotestring

The note populated when the label was marked 'fresh'.

Example: "Initial freshness set"
createdBystring

The unique identifier of the user who created the label.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date and time the label was created (ISO-8601 format).

Example: "2025-01-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the label.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date and time the label was last updated (ISO-8601 format).

Example: "2025-01-12T18:26:10.005365Z"
customFieldsArray of objects(CustomFieldObjectValue)

The custom fields for the label.

statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
permissionsArray of strings

The list of permissions for the label.

Example: []
_isPartialDataboolean

This is true when the user does not have read permissions on the label.

Response
application/json
{
  "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": []
}

Get Label Summaries

Request

GET /labels/summaries

Description

Retrieves summaries of all labels within an organization, including key details such as label names, descriptions, and usage counts.

Security
oauth2
Query
canLinkstring

If true, only returns labels the requesting user has link permission for

statusstring

Filters results by the provided object status

curl -i -X GET \
  'https://developer.hyperproof.app/_mock/hyperproof-api/labels/labels.openapi/summaries?canLink=string&status=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success.

Bodyapplication/jsonArray [
idstring
namestring
createdOnstring
updatedOnstring
permissionsArray of strings
]
Response
application/json
[
  {
    "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": []
  }
]

Get Label

Request

GET /{labelId}

Description

Retrieves details of a specific label by its unique ID, including its name, description, and associated objects.

Security
oauth2
Path
labelIdstringrequired

Unique iD of the label to retrieve.

curl -i -X GET \
  'https://developer.hyperproof.app/_mock/hyperproof-api/labels/labels.openapi/{labelId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success.

Bodyapplication/json
idstring

The unique identifier of the label.

Example: "d88d505d-5199-11ee-a644-522476618ae8"
orgIdstring

The unique identifier for the organization the label belongs to.

Example: "ce83e3cd-5199-11ee-a644-522476618ae8"
namestring

The name of the label.

Example: "Acceptable use of assets"
descriptionstring

The description of the label.

Example: "List of acceptable uses of assets by company employees."
freshnessPolicystring(FreshnessPolicy)

The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.

Enum"none""manual"
freshForDurationstring

The duration after which label becomes stale.

Example: "PT720H"
freshnessstring(Freshness)

The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.

Enum"noFreshness""fresh""expired""unknown"
freshAsOfDatestring

The date when the label was last marked 'fresh' (ISO-8601 format).

Example: "2025-01-12T18:26:10.00.5365Z"
freshAsOfNotestring

The note populated when the label was marked 'fresh'.

Example: "Initial freshness set"
createdBystring

The unique identifier of the user who created the label.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date and time the label was created (ISO-8601 format).

Example: "2025-01-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the label.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date and time the label was last updated (ISO-8601 format).

Example: "2025-01-12T18:26:10.005365Z"
customFieldsArray of objects(CustomFieldObjectValue)

The custom fields for the label.

statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
permissionsArray of strings

The list of permissions for the label.

Example: []
_isPartialDataboolean

This is true when the user does not have read permissions on the label.

Response
application/json
{
  "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": []
}

Update Label

Request

PATCH /{labelId}

Description

Updates an existing label identified by its ID, allowing changes to its name, description, or associated metadata.

Security
oauth2
Path
labelIdstringrequired

Unique ID of the label to update.

Bodyapplication/json
namestring

The name of the label.

Example: "Acceptable use of assets"
descriptionstring

The description of the label.

Example: "List of acceptable uses of assets by company employees."
freshnessPolicystring(FreshnessPolicy)

The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.

Enum"none""manual"
freshForDurationstring

Sets the duration after which the label becomes stale. Supply as a string in standard ISO-8601 duration format ex: P1Y3M2D or PT720H

Example: "PT720H"
freshnessstring(Freshness)

The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.

Enum"noFreshness""fresh""expired""unknown"
freshAsOfDatestring

Sets the date and time when the label was last fresh.

Example: "2025-01-12T18:26:10.00.5365Z"
freshAsOfNotestring

Adds a note when setting freshness. Cannot be set without also updating freshAsOfDate

Example: "Updating expired label freshness"
resetFreshnessNotestring

Adds a note for resetting a label's freshness with an existing freshness policy.

customFieldsArray of objects(CustomFieldObjectValuePatch)
Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","value":"Antonio Moreno"}]
statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
curl -i -X PATCH \
  'https://developer.hyperproof.app/_mock/hyperproof-api/labels/labels.openapi/{labelId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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

Success.

Bodyapplication/json
idstring

The unique identifier of the label.

Example: "d88d505d-5199-11ee-a644-522476618ae8"
orgIdstring

The unique identifier for the organization the label belongs to.

Example: "ce83e3cd-5199-11ee-a644-522476618ae8"
namestring

The name of the label.

Example: "Acceptable use of assets"
descriptionstring

The description of the label.

Example: "List of acceptable uses of assets by company employees."
freshnessPolicystring(FreshnessPolicy)

The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.

Enum"none""manual"
freshForDurationstring

The duration after which label becomes stale.

Example: "PT720H"
freshnessstring(Freshness)

The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.

Enum"noFreshness""fresh""expired""unknown"
freshAsOfDatestring

The date when the label was last marked 'fresh' (ISO-8601 format).

Example: "2025-01-12T18:26:10.00.5365Z"
freshAsOfNotestring

The note populated when the label was marked 'fresh'.

Example: "Initial freshness set"
createdBystring

The unique identifier of the user who created the label.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date and time the label was created (ISO-8601 format).

Example: "2025-01-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the label.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date and time the label was last updated (ISO-8601 format).

Example: "2025-01-12T18:26:10.005365Z"
customFieldsArray of objects(CustomFieldObjectValue)

The custom fields for the label.

statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
permissionsArray of strings

The list of permissions for the label.

Example: []
_isPartialDataboolean

This is true when the user does not have read permissions on the label.

Response
application/json
{
  "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": []
}

Add Label Proof

Request

POST /{labelId}/proof

Description

Adds a proof item to a specified label, associating the evidence with that label for easier organization and tracking.

Security
oauth2
Path
labelIdstringrequired

Unique ID of the label.

Bodymultipart/form-data
curl -i -X POST \
  'https://developer.hyperproof.app/_mock/hyperproof-api/labels/labels.openapi/{labelId}/proof' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data'

Responses

Success.

Bodyapplication/json
idstring

Unique identifier for the proof item

Example: "4eb909de-51af-11ee-a644-522476618ae8"
orgIdstring

Unique identifier for the organization

Example: "ce83e3cd-5199-11ee-a644-522476618ae8"
filenamestring

Name of the uploaded file

Example: "example.txt"
nameOverridestring

Name of proof Hyperproof given by Hyperproof user

contentTypestring

MIME type of the file (e.g.,text/plain)

Example: "text/plain"
fileExtensionstring

File extension (e.g.,txt)

Example: "txt"
sizenumber

File size in bytes

Example: 627
versioninteger

Version of the proof item

sourcestring

Source of the file (e.g.,localComputer)

Example: "localComputer"
sourceVersioninteger

The version of the proof maintained by the source system

ownedBystring

Unique identifier of the user who owns the proof item

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
isPrivateboolean

Whether the proof item is private

uploadedOnstring

The date the proof was uploaded (ISO-8601 format)

Example: "2023-09-12T20:59:47.694353Z"
statusstring

Status of the proof item

Enum"active""archived""deleted""pending""canceled"
Example: "active"
createdBystring

Unique identifier of the user who created the proof item

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date the proof was created (ISO-8601 format)

Example: "2023-09-12T20:59:47.694353Z"
updatedBystring

Unique identifier of the user who last updated the proof item

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date the proof was updated (ISO-8601 format)

Example: "2023-09-12T20:59:47.694353Z"
Response
application/json
{
  "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"
}
® 2026 Hyperproof All Rights Reserved.