Difference between revisions of "API Add Comment"

From IVS Wiki
Jump to: navigation, search
(→‎Response)
 
Line 2: Line 2:
  
 
===Resource URL===
 
===Resource URL===
−
<pre>http://valt.example.com/api/v3/records/{recordid}/comments</pre>
+
<pre>http://valt.example.com/api/v3/comment</pre>
−
''Replace {recordid} with the actual id number of the record. Records given a unique UUID when started.''
 
  
 
===Resource Information===
 
===Resource Information===
Line 11: Line 10:
 
|-
 
|-
 
|'''Headers'''
 
|'''Headers'''
−
|Content-Type:application/json
+
|Content-Type: application/json<br>''or'' Content-Type: multipart/form-data ''(when attaching files)''
 
|-
 
|-
 
|'''Response Type'''
 
|'''Response Type'''
Line 21: Line 20:
  
 
===Parameters===
 
===Parameters===
−
The JSON body must be properly formatted. All fields and values should be enclosed in double quotes and separated by a colon.
+
The JSON body must be properly formatted. All fields and values should be enclosed in double quotes and separated by a colon. The <code>type</code> and <code>recordId</code> fields are always required.
 +
 
 +
====Required Fields====
 
{|class="wikitable"
 
{|class="wikitable"
 
!colspan="2"|Field Name
 
!colspan="2"|Field Name
 +
!Type
 
!Description
 
!Description
−
!Required
 
 
!Example
 
!Example
 
|-
 
|-
−
|colspan="2"|'''event'''
+
|colspan="2"|'''type'''
−
|Comment Text
+
|string
−
|yes
+
|Comment type. Must be one of: <code>simple</code>, <code>duration</code>, or <code>transcription</code>.
−
|Confession
+
|"simple"
 +
|-
 +
|colspan="2"|'''recordId'''
 +
|string (UUID)
 +
|Unique identifier of the recording the comment is being added to.
 +
|"7b931a86-2142-4121-a6f8-2e3197d4c5bf"
 +
|-
 +
|colspan="2"|'''recordTime'''
 +
|int
 +
|Time index in seconds from the beginning of the recording. Required when type is <code>simple</code> or <code>transcription</code>.
 +
|15
 +
|-
 +
|colspan="2"|'''startTime'''
 +
|int
 +
|Start time in seconds from the beginning of the recording. Required when type is <code>duration</code>.
 +
|12
 
|-
 
|-
−
|colspan="2"|'''time'''
+
|colspan="2"|'''endTime'''
−
|Time index in seconds in the recording where the comment will be inserted. An invalid time index can cause an error with the API call.
+
|int
−
|yes
+
|End time in seconds from the beginning of the recording. Required when type is <code>duration</code>.
−
|127
+
|42
 +
|}
 +
 
 +
====Optional Fields====
 +
{|class="wikitable"
 +
!colspan="2"|Field Name
 +
!Type
 +
!Description
 +
!Example
 +
|-
 +
|colspan="2"|'''message'''
 +
|string
 +
|The text content of the comment.
 +
|"This is my comment"
 +
|-
 +
|colspan="2"|'''parentId'''
 +
|int
 +
|The ID of the parent comment when creating a reply.
 +
|5
 +
|-
 +
|colspan="2"|'''audioId'''
 +
|string (UUID)
 +
|Unique identifier for an associated audio recording.
 +
|"8864d73b-a7f3-4412-bda3-d7ef1c1cd2da"
 +
|-
 +
|colspan="2"|'''template'''
 +
|object
 +
|Template attachment for structured comment data. Contains <code>id</code> (int), and optionally <code>data</code> (object) and <code>name</code> (string).
 +
|{"id": 1, "data": {"37": "some value"}, "name": "Entity name"}
 +
|-
 +
|colspan="2"|'''files'''
 +
|array
 +
|Binary file attachments. Requires <code>multipart/form-data</code> content type.
 +
|[binFile1, binFile2]
 +
|-
 +
|colspan="2"|'''color'''
 +
|string
 +
|Name of a color to associate with the comment.
 +
|"red"
 +
|-
 +
|colspan="2"|'''taggedUsers'''
 +
|array
 +
|Array of user IDs to tag in the comment.
 +
|[1, 2]
 +
|-
 +
|colspan="2"|'''taggedUserGroups'''
 +
|array
 +
|Array of user group IDs to tag in the comment.
 +
|[3, 4]
 
|}
 
|}
  
Line 45: Line 109:
 
!Reason
 
!Reason
 
|-
 
|-
−
|200
+
|201
−
|Comment Added Successfully
+
|Comment Created Successfully
 
|-
 
|-
 
|400
 
|400
Line 55: Line 119:
 
|-
 
|-
 
|500
 
|500
−
|JSON Body Formatted Incorrectly
+
|Internal Server Error
 
|}
 
|}
 +
 +
A successful response returns the full Comment object:
  
 
{|class="wikitable"
 
{|class="wikitable"
−
|+JSON Response
+
|+Comment Object Fields
−
!colspan="2"|data
+
!Field
 +
!Type
 +
!Description
 
|-
 
|-
−
|'''comment_add'''
+
|'''id'''
−
|<b>true</b> = comment added successfully, <br><b>false</b> = comment could not be added
+
|int
 +
|Unique identifier of the comment.
 
|-
 
|-
−
|'''time'''
+
|'''parentId'''
−
|Time index for new comment.
+
|int or null
 +
|The ID of the parent comment, if applicable. Null if it has no parent.
 
|-
 
|-
 
|'''message'''
 
|'''message'''
−
|Detailed Status 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 <code>id</code>, <code>username</code>, and <code>displayName</code>.
 +
|-
 +
|'''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 <code>id</code>, <code>name</code>, and <code>size</code> (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==
 
==Examples==
−
===Request===
+
===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.
 
The sample JSON body below is formatted with line breaks and indentation to make it easier to read. This is '''not''' required.
−
<pre>https://ivstest1.ad.ipivs.com/api/v3/records/616/comments?access_token=e82632d19c523678fea3d1016c6df9e9</pre>
+
<pre>https://ivstest1.ad.ipivs.com/api/v3/comment?access_token=e82632d19c523678fea3d1016c6df9e9</pre>
 
  <nowiki>
 
  <nowiki>
 
{
 
{
−
   "event":"API Comment",
+
   "type": "simple",
−
   "time": 30
+
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
 +
  "recordTime": 30,
 +
  "message": "API Comment"
 +
}
 +
</nowiki>
 +
 
 +
===Duration Marker Comment===
 +
====Request====
 +
<pre>https://ivstest1.ad.ipivs.com/api/v3/comment?access_token=e82632d19c523678fea3d1016c6df9e9</pre>
 +
<nowiki>
 +
{
 +
  "type": "duration",
 +
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
 +
   "startTime": 12,
 +
  "endTime": 42,
 +
  "message": "Marker spanning a range"
 +
}
 +
</nowiki>
 +
 
 +
===Template Comment===
 +
====Request====
 +
<pre>https://ivstest1.ad.ipivs.com/api/v3/comment?access_token=e82632d19c523678fea3d1016c6df9e9</pre>
 +
<nowiki>
 +
{
 +
  "type": "simple",
 +
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
 +
  "recordTime": 10,
 +
  "template": {
 +
    "id": 1,
 +
    "data": {
 +
      "37": "some value"
 +
    },
 +
    "name": "Entity name"
 +
  }
 
}
 
}
 
</nowiki>
 
</nowiki>
Line 87: Line 244:
 
  <nowiki>
 
  <nowiki>
 
{
 
{
−
"data":{
+
  "id": 2,
−
"comment_add": true,
+
  "parentId": null,
−
"message": "comment add",
+
  "message": "API Comment",
−
"time": 30
+
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
−
}
+
  "recordTime": 30,
 +
  "audioId": null,
 +
  "template": null,
 +
  "author": {
 +
    "id": 2,
 +
    "displayName": "John Smith",
 +
    "username": "jsmith"
 +
  },
 +
  "files": [],
 +
  "updatedBy": null,
 +
  "color": "red",
 +
  "replies": [],
 +
  "taggedUsers": [],
 +
  "taggedUserGroups": [],
 +
  "createdAt": 1737109634,
 +
  "updatedAt": 1737109634
 
}
 
}
 
</nowiki>
 
</nowiki>
Line 99: Line 271:
 
  <nowiki>
 
  <nowiki>
 
{
 
{
−
"error":{
+
  "error": {
−
"code": 500,
+
    "code": 500,
−
"message": "Internal Server Error"
+
    "message": "Internal Server Error"
 +
  }
 
}
 
}
−
}
 
−
 
 
</nowiki>
 
</nowiki>

Latest revision as of 15:14, 11 June 2026

This API call will add a new comment to the specified recording. This call can be used on a recording in progress.

Resource URL

http://valt.example.com/api/v3/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

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 the comment is being added to. "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 text content of the comment. "This is my comment"
parentId int The ID of the parent comment when creating a reply. 5
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 Binary file attachments. Requires multipart/form-data content type. [binFile1, binFile2]
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
201 Comment Created Successfully
400 Invalid Request (See Response for Specific Error)
401 Unauthorized
500 Internal Server Error

A successful response returns the full 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?access_token=e82632d19c523678fea3d1016c6df9e9
{
  "type": "simple",
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
  "recordTime": 30,
  "message": "API Comment"
}

Duration Marker Comment

Request

https://ivstest1.ad.ipivs.com/api/v3/comment?access_token=e82632d19c523678fea3d1016c6df9e9
{
  "type": "duration",
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
  "startTime": 12,
  "endTime": 42,
  "message": "Marker spanning a range"
}

Template Comment

Request

https://ivstest1.ad.ipivs.com/api/v3/comment?access_token=e82632d19c523678fea3d1016c6df9e9
{
  "type": "simple",
  "recordId": "7b931a86-2142-4121-a6f8-2e3197d4c5bf",
  "recordTime": 10,
  "template": {
    "id": 1,
    "data": {
      "37": "some value"
    },
    "name": "Entity name"
  }
}

Successful Response

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

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

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"
  }
}
Retrieved from "https://ivs.help/wiki/index.php?title=API_Add_Comment&oldid=17599"