API Edit Comment

This API call will update an existing comment by its ID.

Resource URL

http://valt.example.com/api/v3/comment/update/{id}

Replace {id} with the actual ID number of the comment.

Resource Information

Method	POST
Headers	Content-Type: application/json or Content-Type: multipart/form-data (when attaching files)
Response Type	JSON
Authentication Required	Yes

Parameters

Path Parameters

Parameter	Description	Example
id	The ID of the comment to update.	42

Request Body

The JSON body must be properly formatted. All fields and values should be enclosed in double quotes and separated by a colon. The type and recordId fields are always required.

Required Fields

Field Name		Type	Description	Example
type		string	Comment type. Must be one of: simple, duration, or transcription.	"simple"
recordId		string (UUID)	Unique identifier of the recording associated with the comment.	"7b931a86-2142-4121-a6f8-2e3197d4c5bf"
recordTime		int	Time index in seconds from the beginning of the recording. Required when type is simple or transcription.	15
startTime		int	Start time in seconds from the beginning of the recording. Required when type is duration.	12
endTime		int	End time in seconds from the beginning of the recording. Required when type is duration.	42

Optional Fields

Field Name		Type	Description	Example
message		string	The updated text content of the comment.	"Updated comment text"
audioId		string (UUID)	Unique identifier for an associated audio recording.	"8864d73b-a7f3-4412-bda3-d7ef1c1cd2da"
template		object	Template attachment for structured comment data. Contains id (int), and optionally data (object) and name (string).	{"id": 1, "data": {"37": "some value"}, "name": "Entity name"}
files		array	New binary file attachments to add. Requires multipart/form-data content type.	[binFile1, binFile2]
fileIds		array of int	IDs of existing file attachments to retain on the comment. Files not listed here will be removed.	[20, 21]
color		string	Name of a color to associate with the comment.	"red"
taggedUsers		array	Array of user IDs to tag in the comment.	[1, 2]
taggedUserGroups		array	Array of user group IDs to tag in the comment.	[3, 4]

Response

Code	Reason
200	Comment Updated Successfully
400	Invalid Request (See Response for Specific Error)
401	Unauthorized
500	Internal Server Error

A successful response returns the full updated Comment object:

Comment Object Fields

Field	Type	Description
id	int	Unique identifier of the comment.
parentId	int or null	The ID of the parent comment, if applicable. Null if it has no parent.
message	string or null	The text content of the comment.
recordId	string	Unique identifier for the associated record.
recordTime	string	Seconds from the beginning of the associated record.
createdAt	int	Unix timestamp when the comment was created.
updatedAt	int	Unix timestamp when the comment was last updated.
author	User object	The author of the comment. Contains id, username, and displayName.
updatedBy	User object or null	The user who last updated the comment. Null if never updated.
audioId	string or null	Unique identifier for the associated audio, if applicable.
template	Template object or null	Template attachment, if applicable.
files	array	List of file attachments. Empty array if no files are attached. Each file contains id, name, and size (bytes).
color	string	Color name associated with the comment.
replies	array	Array of reply comments.
taggedUsers	array	Array of users tagged in the comment.
taggedUserGroups	array	Array of user groups tagged in the comment.

Examples

Simple Text Comment

Request

The sample JSON body below is formatted with line breaks and indentation to make it easier to read. This is not required.

https://ivstest1.ad.ipivs.com/api/v3/comment/update/42?access_token=e82632d19c523678fea3d1016c6df9e9

{
  "type": "simple",
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
  "recordTime": 15,
  "message": "Updated comment text"
}

Duration Marker Comment

Request

https://ivstest1.ad.ipivs.com/api/v3/comment/update/42?access_token=e82632d19c523678fea3d1016c6df9e9

{
  "type": "duration",
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
  "startTime": 12,
  "endTime": 42,
  "message": "Updated marker spanning a range"
}

Template Comment

Request

https://ivstest1.ad.ipivs.com/api/v3/comment/update/42?access_token=e82632d19c523678fea3d1016c6df9e9

{
  "type": "simple",
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
  "recordTime": 10,
  "template": {
    "id": 1,
    "data": {
      "37": "some value"
    },
    "name": "Entity name"
  }
}

Retaining Existing File Attachments

Request

Use fileIds to keep existing files on the comment. Files whose IDs are not included will be removed.

https://ivstest1.ad.ipivs.com/api/v3/comment/update/42?access_token=e82632d19c523678fea3d1016c6df9e9

{
  "type": "simple",
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
  "recordTime": 15,
  "fileIds": [20, 21],
  "message": "Updated message with existing files retained"
}

Successful Response

Sample response is shown with line breaks to make it more readable. Actual responses will not include line breaks.

{
  "id": 42,
  "parentId": null,
  "message": "Updated comment text",
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
  "recordTime": 15,
  "audioId": null,
  "template": null,
  "author": {
    "id": 2,
    "displayName": "John Smith",
    "username": "jsmith"
  },
  "files": [],
  "updatedBy": {
    "id": 2,
    "displayName": "John Smith",
    "username": "jsmith"
  },
  "color": "red",
  "replies": [],
  "taggedUsers": [],
  "taggedUserGroups": [],
  "createdAt": 1737109634,
  "updatedAt": 1737111434
}

Failure Response

Sample response is shown with line breaks to make it more readable. Actual responses will not include line breaks.

{
  "error": {
    "code": 500,
    "message": "Internal Server Error"
  }
}