Revision as of 03:44, March 25, 2017 by Sschlich (talk | contribs)
Jump to: navigation, search

Recording Label API

ENTIRE PAGE IS NEW

Source: https://intranet.genesys.com/display/RP/Summary+of+Label+APIs+to+be+documented

Overview

Use this API to create and administer label definitions. A label definition defines a label, which can then be applied to a recording. For example, a label definition could be created to mark a recording for further review.

Access this API and its Operations at the base path /api/v2. For example:
   http://localhost:8080/api/v2/recording_label_definitions

Prerequisites

  • Configure the Elasticsearch schema v2 to enable support for labels and non-deletion features. For existing deployments, follow the migration steps here: Migrating an Existing Elasticsearch Deployment to Schema V2. New deployments after GIR version 8.5.214.00 will have Elasticsearch schema v2 enabled by default.

Permissions

Specific permissions support your ability to create and administer label definitions, and to set and remove labels from recordings. See: Configuring Permissions for Recording Labels.

Creating a label definition

Request URL /recording-label-definitions/
HTTP Method POST
Required Roles
  • Administrator
  • Supervisor
  • Agent
Required Permissions N/A RECORDING_PERMISSION_ADD_LABEL_DEFINITION


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Description Notes
name String Yes N/A The name of the label definition.
  • Is case-sensitive.
  • Must only contain ASCII characters.
  • Must be unique among other label definitions.
  • Must not start with two underscores("__") as it is reserved.
displayName String No Defaults to the value of name. The display name of the label definition. Must be unique among other label definitions.
description String No Empty string The description of the label definition.

Response

HTTP Status
Status Codes Situations
201 CREATED The label definition was created successfully.
400 BAD REQUEST Bad request received.
403 FORBIDDEN Forbidden to create the label definition.
409 CONFLICT The label definition was not created as one with the same name exists already.


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Situations Notes
statusCode Integer Yes 0 N/A Label definition was created.
1 (RequiredParameterMissing) The required payload attributes are missing.
2 (InvalidRequestParameter) The constraints of payload attributes are not met.
3 (OperationForbidden) The requesting user does not have the permissions required or is attempting to create with reserved name.
18 (ResourceAlreadyExists) A label definition with the same name exists already.
20 (unauthenticated) The requesting user is not properly authenticated or using a non-ops API as an ops user.
statusMessage String No
  • Not specified.
  • A message providing information.
 N/A The statusMessage will provide more information about a failure if statusCode is not 0.
labelDefinition JSON object No JSON object containing the label definition.
  • path (string): The path to the resource.
  • name (string): The name of the label definition.
  • displayName (string, optional): The display name of the label definition.
  • description (string, optional): The description of the label definition.
 N/A The newly created label definition or existing one in case of an attempt to create an already existing one.



Example Request

POST /recording-label-definitions/
{
        "name": "SomeLabelDefinition",
        "displayName": "New Label Definition",
        "description": "A new label definition"
 }


Example Responses

{
	"statusCode": 0,
	"labelDefinition": {
		"path": "/recording-label-definitions/2365adc7-67bb-448e-b32d-04731faa9231",
		"name": "SomeLabelDefinition",
		"displayName": "New Label Definition",
		"description": "A new label definition"
	}
}
{
	"statusCode": 2,
	"statusMessage": "Invalid value specified."
}
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
{
	"statusCode": 18,
	"statusMessage": "Resource exists already."
	"labelDefinition": {
		"path": "/recording-label-definitions/a6a6f1d9-788a-47b4-bdeb-80b3d598cfa6",
		"name": "ExistingLabelDefinition",
		"displayName": "Existing Label Definition."
		"description": "An existing label definition"
	}
}

Updating a label definition

Request URL /recording-label-definitions/<labelDefinitionId>
HTTP Method PUT
Required Roles
  • Administrator
  • Supervisor
  • Agent
Required Permissions N/A RECORDING_PERMISSION_ADD_LABEL_DEFINITION

Note: You can use the path attribute from the response returned by the GET or POST operations for label definition.


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Description Notes
name String Yes N/A The name of the label definition.

Name cannot be updated—must be specified to the same value as the existing name.

displayName String No Default to the value of name if not specified. The display name of the label definition. Must be unique among other label definitions.
description String No Empty string The description of the label definition.

Response

HTTP Status
Status Codes Situations
200 OK The label definition was updated successfully.
400 BAD REQUEST Bad request received.
403 FORBIDDEN Forbidden to update the label definition.
404 NOT FOUND Cannot find the label definition to update.


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Situations Notes
statusCode Integer Yes 0 N/A Label definition was updated.
1 (RequiredParameterMissing) The required payload attributes are missing.
2 (InvalidRequestParameter) The constraints of payload attributes are not met.
3 (OperationForbidden) The requesting user does not have the permissions required or is attempting to update with different name.
6 (ResourceNotFound) The specified label definition cannot be found.
20 (Unauthenticated) The requesting user is not properly authenticated or using a non-ops API as an ops user.
statusMessage String No
  • Not specified.
  • A message providing information.
 N/A The statusMessage will provide more information about a failure if statusCode is not 0.
labelDefinition JSON object Yes
  • name (string): The name of the label definition.
  • displayName (string, optional): The display name of the label definition.
  • description (string, optional): The description of the label definition.
  • path (string, optional): The path of the label definition.
  • Must be unique among other label definitions.
 N/A


Example Request

PUT /recording-label-definitions/{labelDefinitionId}
{
        "name": "SomeLabelDefinition",
        "displayName": "New Label Definition",
        "description": "A new label definition"
 }


Example Responses

{
	"statusCode": 0,
	"labelDefinition": {
		"path": "/recording-label-definitions/2365adc7-67bb-448e-b32d-04731faa9231",
		"name": "SomeLabelDefinition",
		"displayName": "Updated Label Definition",
		"description": "An updated label definition"
	}
}
 
{
	"statusCode": 2,
	"statusMessage": "Invalid value specified."
}
 
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
 
{
	"statusCode": 6,
	"statusMessage": "Custom label definition cannot be found."
}

{
	"statusCode": 20,
	"statusMessage": "Access denied."
}

Deleting a label definition

Request URL /recording-label-definitions/{labelDefinitionId}
HTTP Method DELETE
Required Roles
  • Administrator
  • Supervisor
  • Agent
Required Permissions N/A RECORDING_PERMISSION_DELETE_LABEL_DEFINITION

Note: You can use the path attribute from the response returned by the GET or POST operations for label definition.


Response

HTTP Status
Status Codes Situations Notes
200 OK The label definition was deleted successfully.
403 FORBIDDEN Forbidden to delete the label definition.
404 NOT FOUND Cannot find the label definition to delete.


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Situations Notes
statusCode Integer Yes 0 N/A The label definition was deleted.
3 (OperationForbidden) The requesting user does not have the permissions required.
6 (ResourceNotFound) The specified label definition cannot be found.
20 (Unauthorized) The requesting user is ops.
statusMessage String No
  • Not specified.
  • A message providing information.
 N/A The statusMessage will provide more information about a failure if statusCode is not 0.

Example Responses

{
	"statusCode": 0
}
 
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
 
{
	"statusCode": 5,
	"statusMessage": "Access denied."
}
 
{
	"statusCode": 6,
	"statusMessage": "Custom label definition cannot be found."
}

Retrieving label definitions

Request URL /recording-label-definitions
HTTP Method GET
Required Roles
  • Administrator
  • Supervisor
  • Agent
Required Permissions N/A N/A

Note: Returns all the label definitions.


Parameters
Attributes JSON Data Type Mandatory Possible Values Default Value Description Notes
type Comma-separated string of label definition types. No
  • Reserved
  • Custom
 N/A The type of label definition to return. If the type is not specified, the Reserved and Custom label definitions are returned.

If type is empty ("?type="), the Reserved and Custom label definitions are returned.

If type contains a valid value, only the type of label definition that was specified is returned.

fields Comma-separated string of fields. No
  • name
  • displayName
  • description
  • *
 N/A
  • The fields to be returned from the label definition.
  • Path is always returned.
  • Use "*" to return all fields.

If fields is not specified, the path and name will be returned.

If fields is empty("?fields="), the path is returned.

If fields contains a valid value, the path and the specified fields are returned.

Response

HTTP Status Fields Possible Values Situations
200 OK statusCode 0 (Ok) Retrieval of all label definitions succeeded.
7 (PartialResponse) Retrieval of some label definitions failed.
12 (UnableToRetrieveResource) Retrieval of all label definitions failed.
labelDefinitions An array of label definitions. Always

Label definition response data

Fields Description
path The path of the label definition.
name The name of the label definition.
type The type of the label definition.
displayName The display name of the label definition.
description The description of the label definition.

Example

GET /recording-label-definitions
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550b",
      "name": "importantTag"
    }
  ]
}
 
GET /recording-label-definitions?fields=
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B"
    }
  ]
}

GET /recording-label-definitions?fields=*
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated",
      "type": "Reserved",
      "displayName": "Evaluated",
      "description": "A label indicating the interaction on which it is applied has been evaluated."
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment",
      "type": "Custom",
      "displayName": "Comment",
      "description": "A label for recording comment."
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag",
      "type": "Custom",
      "displayName": "Important",
      "description": "A label to tag recordings that are important."
    }
  ]
}
 
GET /recording-label-definitions?fields=name,displayName
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated",
      "displayName": "Evaluated"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment",
      "displayName": "Comment"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag",
      "displayName": "Important"
    }
  ]
}
 
GET /recording-label-definitions?fields=*&type=Custom
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment",
      "type": "Custom",
      "displayName": "Comment",
      "description": "A label for recording comment."
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag",
      "type": "Custom",
      "displayName": "Important",
      "description": "A label to tag recordings that are important."
    }
  ]
}
 
GET /recording-label-definitions?type=Reserved
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated"
    }
  ]
}

Adding a label to a recording

Request URL /recordings/<recid>/labels
HTTP Method POST
Required Roles
  • Administrator
  • Supervisor
  • Agent
Required Permissions N/A RECORDING_PERMISSION_ADD_LABEL


Payload
Properties Type Mandatory Default Values Description
name String Yes N/A The name of the label definition to be added to the recording.
content JSON Object No empty The content associated with the label to be added to the recording. This is a free-form JSON element that accepts valid JSON types.


Response

HTTP Status
Status Codes Situations
201 CREATED The label has been added to the recording successfully.
403 FORBIDDEN
  • The recording requested can be found, but the label cannot be added to it for some reason (for example, region not matched, requesting user cannot access the recording).
  • The recording requested cannot be found.
  • There already exists a label instance that is identical to the one to add on the same recording.
  • The label definition name cannot be found.
Payload
Fields Type Mandatory Possible Values Situations Notes
statusCode Integer Yes 0 (Ok) The label was added to the requested recording successfully.
13 (UnableToCreateResource) Label failed to be added to the requested recording.
18 (ResourceAlreadyExists) There already exists a label instance that is identical to the one to add on the same recording.
statusMessage String No
  • Not specified.
  • A message providing information.
 The statusMessage will provide more information about a failure if statusCode is not 0.
id String No ID of the created label. HTTP status is 201.
path String No Path of the created label. HTTP status is 201.

Example Requests

POST /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels 
{ 
   "name" :  "comment" , 
   "content" : { 
     "time" :  "2017-01-01T15:07:17Z" , 
     "text" :  "This is an awesome comment!" 
   } 
} 
   
POST /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels 
{ 
   "name" :  "importantTag" 
} 
   
POST /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels 
{ 
   "name" :  "comment" , 
   "content" : { 
     "time" :  "2017-08-05T15:07:17Z" , 
     "rating" :  "excellent" , 
     "by" : { 
       "userName" :  "supervisor_1" , 
       "firstName" :  "super" , 
       "lastName" :  "visor" 
     } 
   } 
}


Example Response

201 CREATED
{
  "statusCode": 0,
  "id": "8c9a634f-343d-49b3-8322-b571be520b31",
  "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31"
}
  
 
403 FORBIDDEN
{
  "statusCode": 13,
  "statusMessage": "Cannot add label to recording."
}

Adding a label to multiple recordings

Request URL /recording-labels
HTTP Method POST
Required Roles
  • Administrator
  • Supervisor
  • Agent
Required Permissions N/A RECORDING_PERMISSION_ADD_LABEL


Payload
Level-0 Properties Level-1 Properties Type Mandatory Default Values Description
recordingIds N/A JSON Array Yes N/A The list of recording IDs that the label needs to be added to.
label name String Yes N/A The name of the label definition to be added to the recordings.
content JSON Object No empty The content associated with the label to be added to the recordings. This is a free-form JSON element that accepts valid JSON types.


Response

HTTP Status Situations
200 OK The requested list of recordings is empty.
201 CREATED The label has been added to all the requested recordings successfully and at least one label resource has been created.
207 MULTI-STATUS The label failed to be added to some but not all of the requested recordings, but succeeded for the rest.
403 FORBIDDEN The label failed to be added to all of the requested recordings.


Payload
Fields Type Mandatory Possible Values Situations Notes
statusCode Integer Yes 0 (Ok) The label is added to all the requested recordings successfully.
7 (PartialResponse) The label succeeded on some of the requested recordings, but failed on the rest.
13 (UnableToCreateResource) The label failed to be added to all the requested recordings.
statusMessage String No
  • Not specified.
  • A message providing information.
 The statusMessage will provide more information about a failure if statusCode is not 0.
succeeded JSON Array Yes The recording id to created label URI mapping for the recordings to which label has been successfully added. It will always be displayed in the response but can be empty.
failed JSON Array Yes A list of blocks that describes the failures. It will always be displayed in the response but can be empty.

Example Request

POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "comment" , 
     "content" : { 
       "time" :  "2017-08-05T15:07:17Z" , 
       "text" :  "This is an awesome comment!" 
     } 
   } 
} 
   
POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "importantTag" 
   } 
} 
   
POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "comment" , 
     "content" : { 
       "time" :  "2017-08-05T15:07:17Z" , 
       "rating" :  "excellent" , 
       "by" : { 
         "userName" :  "supervisor_1" , 
         "firstName" :  "super" , 
         "lastName" :  "visor" 
       } 
     } 
   } 
}


Example Response

200 OK
{
  "statusCode": 0,
  "succeeded": [],
  "failed": []
}
  
201 CREATED
{
  "statusCode": 0,
  "succeeded": [
    {
      "recordingId": "bf697521-3ffc-46f1-b840-f7230e940df3",
      "id": "8c9a634f-343d-49b3-8322-b571be520b31",
      "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31"
    },
    {
      "recordingId": "76705af9-65d4-46a4-af84-e984ef09ec5d",
      "id": "1574da8d-ed8d-419d-b2e7-f00c1dabe0dc",
      "path": "/recordings/76705af9-65d4-46a4-af84-e984ef09ec5d/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc"
    }
  ],
  "failed": []
}
 
207 MULTI-STATUS
{
  "statusCode": 7,
  "statusMessage": "Add of label failed on some recordings.",
  "succeeded": [
    {
      "recordingId": "bf697521-3ffc-46f1-b840-f7230e940df3",
      "id": "8c9a634f-343d-49b3-8322-b571be520b31",
      "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31"
    }
  ],
  "failed": [
    {
      "recordingId": "76705af9-65d4-46a4-af84-e984ef09ec5d",
      "statusCode": 13,
      "statusMessage": "Cannot add label."
    },
    {
      "recordingId": "d0464cf3-f81f-49b5-bc0e-bd166161d756",
      "statusCode": 13,
      "statusMessage": "Internal error."
    }
  ]
}
 
403 FORBIDDEN
{
  "statusCode": 13,
  "statusMessage": "Add of label failed on all the recordings.",
  "succeeded": [],
  "failed": [
    {
      "recordingId": "d0464cf3-f81f-49b5-bc0e-bd166161d756",
      "statusCode": 13,
      "statusMessage": "Cannot add label."
    }
  ]
}

Updating a label on a recording

Request URL /recordings/<recid>/labels/<id>
HTTP Method PUT
Required Roles
  • Administrator
  • Supervisor
  • Agent
Required Permissions N/A RECORDING_PERMISSION_ADD_LABEL


Payload
Properties Type Mandatory Default Values Description
content JSON Object No empty The content associated with the label to be updated to the

recording. This is a JSON object which can be customized depending on the application. The examples below show a possible use case of adding user comments on a recording.


Effect

When a label is updated:

  • The content of the label is updated to the one that is specified in the payload.
  • The field createTime is updated to the time when the update action was performed.
  • The field createUser is updated to the username of the user who requested the update.

Response

HTTP Status
Status Codes Situations
200 OK The requested label has been updated successfully.
403 FORBIDDEN
  • The recording requested can be found but the label cannot be updated to it for whatever reason (for example, region not matched, requesting user cannot access the recording).
  • The recording requested cannot be found.
404 NOT FOUND The requested label cannot be found.


Payload
Fields Type Mandatory Possible Values Situations Notes
statusCode Integer Yes 0 (Ok) The label has been updated to the requested recording successfully.
6 (ResourceNotFound) The label cannot be found.
15 (UnableToUpdateResource)
  • The recording requested can be found but the label cannot be updated to it for whatever reason (for example, region not matched, requesting user cannot access the recording).
  • The recording requested cannot be found.
statusMessage String No
  • Not specified.
  • A message providing information.
 The statusMessage will provide more information about a failure if statusCode is not 0.

Example Request

PUT /recordings/<labels> 
{ 
   "content" : { 
     "time" :  "2017-08-05T15:07:17Z" , 
     "text" :  "This is an awesome comment!" 
   } 
} 
   
PUT /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/5dbdb466-5377-4351-bd1e-c4066437d410 
{ 
   "content" : { 
     "time" :  "2017-08-05T15:07:17Z" , 
     "rating" :  "excellent" 
     "by" : { 
         "userName" :  "supervisor_1" , 
         "firstName" :  "super" , 
         "lastName" :  "visor" 
     } 
   } 
}

Example Response

200 OK 
{ 
   "statusCode" : 0 
} 
  
403 FORBIDDEN 
{ 
   "statusCode" : 15, 
   "statusMessage" :  "Cannot update the label for recording." 
} 
   
404 NOT FOUND 
{ 
   "statusCode" : 6, 
   "statusMessage" :  "Requested label cannot be found." 
}

Deleting a label from a recording

Request URL /recordings/<recid>/labels/<id>
HTTP Method DELETE
Required Roles
  • Administrator
  • Supervisor
  • Agent
Required Permissions N/A RECORDING_PERMISSION_DELETE_LABEL


Response

HTTP Status
Status Codes Situations
200 OK
  • The label has been deleted from the requested recording successfully.
403 FORBIDDEN
  • The recording requested can be found but the label cannot be deleted from it for some reason (for example, region not matched, requesting user cannot access the recording).
  • The recording requested cannot be found.


Payload
Fields Type Mand-
atory 		Possible
Values 		Situations Notes
statusCode Integer Yes 0 (Ok)

The label has been deleted from the requested recording successfully.
  OR
The label cannot be found within the requested recording.

14 (UnableToDeleteResource) The label failed to be deleted from the requested recording.
statusMessage String No
  • Not specified.
  • A message providing information.
 The statusMessage will provide more information about a failure if statusCode is not 0.

Example Response

Delete Label Instance From Recording Response 

DELETE /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
200 OK 
{ 
   "statusCode" : 0 
} 
   
DELETE /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31 
403 FORBIDDEN 
{ 
   "statusCode" : 14, 
   "statusMessage" :  "Label failed to be deleted from the recording." 
}

Getting all labels from a recording

Request URL /recordings/<recid>/labels
HTTP Method GET
Required Roles
  • Administrator
  • Supervisor
  • Agent
Required Permissions N/A


Parameters
Fields Subfields Type Mandatory Possible Values Situations Notes
statusCode Integer Yes 0 (Ok) The label was added to the requested recording successfully.
13 (UnableToCreateResource) Label failed to be added to the requested recording.
18 (ResourceAlreadyExists) There already exists a label instance that is identical to

the one to add on the same recording.

statusMessage String No

  • Not specified.

  • A message providing information.

The statusMessage will provide more information about a

failure if statusCode is not 0.

labels







Array of labels No Each label will have the fields requested. If fields parameter is received.
id String No The ID of the created label. If fields parameter is received.
path String No The path of the created label. If fields parameter is received.
name String No The name of the label definition. If fields parameter is received.
createTime String No The time when the label was last updated. If fields parameter is received.
createUser String No The username of the user who last updated the label on the

recording.

If fields parameter is received.
content JSON object No JSON object containing custom content if populated. If fields parameter is received The content is a JSON object that can contain custom data

information.

paths Array of paths no The array of paths of label instances associated with this

recording.

If fields parameter is not present.


Response

HTTP Status
Status Codes Situations
200 OK The retrieval of the labels succeeded or there are no labels associated with the recording.
403 FORBIDDEN
  • The recording for which the labels are requested can be found but cannot be retrieved for some reason (for example, region not matched, requesting user cannot access the recording).
  • The recording for which the labels are requested cannot be found.


Payload
Fields Subfields Type Mandatory Possible Values Situations Notes
statusCode Integer Yes 0 (Ok) The label was added to the requested recording successfully.
13 (UnableToCreateResource) The label failed to be added to the requested recording.
18 (ResourceAlreadyExists) There already exists a label instance that is identical to the one to add to the same recording.
statusMessage String No
  • Not specified.
  • A message providing information.
 The statusMessage will provide more information about a failure if statusCode is not 0.
labels Array of labels No Each label will have the fields requested. Always
id String No The ID of the created label. Always
path String No The path of the created label. Always
name String No The name of the label definition. Not specified or if fields parameter is received.
createTime String No The time when the label was last updated. If the fields parameter is received.
createUser String No The username of the user who last updated the label on the recording. If the fields parameter is received.
content JSON object No The JSON object containing custom content, if populated. If the fields parameter is received. The content is a JSON object that can contain custom data.

Example Response

GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df5/labels
200 OK
{
   "statusCode" : 0,
   "labels" : []
}
  
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df4/labels
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31" ,
       "name" :  "comment" ,
       "id" :  "8c9a634f-343d-49b3-8322-b571be520b31"
     }
   ]
}
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31" ,
      
       "id" :  "8c9a634f-343d-49b3-8322-b571be520b31"
     }
   ]
}
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=content
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31",
       "id" :  "8c9a634f-343d-49b3-8322-b571be520b31" ,
       "content" : {
         "time" :  "2017-04-22T12:42:44.000+0000" ,
         "comment" :  "This is an awesome comment!"
       }
     }
   ]
}
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=*
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels
/8c9a634f-343d-49b3-8322-b571be520b31" ,
       "name" :  "comment" ,
       "id" :  "8c9a634f-343d-49b3-8322-b571be520b31" ,
       "createTime" :  "2017-04-22T12:42:46.000+0000" ,
       "createUser" :  "supervisor" ,
       "content" : {
         "time" :  "2017-04-22T12:42:44.000+0000" ,
         "comment" :  "This is an awesome comment!"
       }
     }
   ]
}
  
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels
403 FORBIDDEN
{
   "statusCode" : 12,
   "statusMessage" :  "Recording cannot be found."
}
  
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=*
403 FORBIDDEN
{
   "statusCode" : 12,
   "statusMessage" :  "Recording cannot be accessed."
}

Getting a specific label from a recording

Request URL /recordings/<recid>/labels/<id>
HTTP Method GET
Required Roles
  • Administrator
  • Supervisor
  • Agent
Required Permissions N/A


Response

HTTP Status
Status Codes Situations
200 OK The retrieval of the label succeeded.
403 FORBIDDEN
  • The recording for which the label is requested can be found but cannot be retrieved for some reason (for example, region not matched, requesting user cannot access the recording).
  • The recording for which the label is requested cannot be found.
404 NOT FOUND
  • The label cannot be found by the ID specified.


Payload
Fields Type Mandatory Possible Values Situations Notes
statusCode Integer Yes 0 (Ok) Retrieval of the label succeeded.
6 (ResourceNotFound) The label cannot be found.
12 (UnableToRetrieveResource) Retrieval of the label failed.
statusMessage String No
  • Not specified.
  • A message providing information.
 The statusMessage will provide more information about a failure if statusCode is not 0.
label JSON Object No The actual data of the label requested.

A label contains the following information:

  • Path (string): the path of the label.
  • Name (string): the name of the label.
  • Type (string): the type of the label.
  • ID (string): the ID of the label.
  • createTime (string): the time the label was last created or updated.
  • createUser (string): the last user that created or updated the label.
  • content (a JSON object): an object containing custom data, if populated.
 It will only be displayed if the retrieval of the label succeeded.

Example Responses

GET /recordings/bf697521-3ffc-46f1-b840-f7230e940da3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
200 OK 
{ 
   "statusCode" : 0, 
   "label" : { 
     "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940da3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc" , 
     "name" :  "comment" , 
     "id" :  "1574da8d-ed8d-419d-b2e7-f00c1dabe0dc" , 
     "createTime" :  "2017-04-20T04:11:02.000+0000" , 
     "createUser" :  "supervisor" , 
     "content" : {} 
   } 
} 
   
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
403 FORBIDDEN 
{ 
   "statusCode" : 12, 
   "statusMessage" :  "Recording cannot be found." 
} 
   
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
404 NOT FOUND 
{ 
   "statusCode" : 6, 
   "statusMessage" :  "Label cannot be found for the recording." 
}
Comments or questions about this documentation? Contact us for support!