Note API

This article describes API calls that configure Collaborative Items (notes) and their comments (note comments).

  • /api/note: Allows retrieving, creating, updating, and deleting notes.
  • /api/note_comment: Allows retrieving, creating, and updating note comments.

Table of contents:

  1. Access Admin >System > API Toolkit
  2. Configure Notes
    1. Get Notes
    2. Create Note
    3. Edit Note
    4. Delete Note
  3. Configure Note Comments
    1. Get Note Comments
    2. Create Note Comment
    3. Delete Note Comment

1. Access Admin >System > API Toolkit

2. Configure Notes

2.1. Get Notes

The GET request to /api/note returns all available notes.

  1. Item: note
  2. Method: GET
  3. Optionally, filter the results:
    • ID: Return a note with the entered ID
    • element: Return all notes about the element with the entered ID
    • dimensions_value: Return all notes about the entered dimension value
  4. Enter an API Token
  5. [Run request]

Example Response 

{
  "notes": [
    {
      "id": 97,
      "element": 122373,
      "dimension_value": 0,
      "text": "Created a new report",
      "created_time": "2025-04-12 15:12:40",
      "user_id": 118,
      "username": "robert",
      "display_name": "Robert",
      "comments": [
        {
          "user_comment_id": 1914,
          "scope": "note",
          "user_note_id": 97,
          "alert_event_id": 0,
          "notable_event_id": 0,
          "user_annotation_id": 0,
          "text": "@robert Are you available for discussion today?",
          "last_updated_time": "2025-04-12 15:14:55",
          "user_id": 177,
          "username": "JamesAdmin",
          "display_name": "James Admin"
        },
        {
          "user_comment_id": 1913,
          "scope": "note",
          "user_note_id": 97,
          "alert_event_id": 0,
          "notable_event_id": 0,
          "user_annotation_id": 0,
          "text": "Thank you, I'll review this tomorrow!",
          "last_updated_time": "2025-04-12 15:14:01",
          "user_id": 177,
          "username": "JamesAdmin",
          "display_name": "James Admin"
        }
      ]
    },
    {
      "id": 93,
      "element": 1339,
      "dimension_value": 11728,
      "text": "Shared with the team",
      "created_time": "2022-08-04 14:34:47",
      "user_id": 120,
      "username": "Yevgeniya",
      "display_name": "Yevgeniya",
      "comments": []
    },
    {
      "id": 92,
      "element": 1731,
      "dimension_value": 8,
      "text": "comment here!\n",
      "created_time": "2022-02-16 21:47:01",
      "user_id": 88,
      "username": "Anna",
      "display_name": "Anna Kennedy",
      "comments": []
    }
  ]
}

Fields Description

Field Name Value Type Description
id integer The ID of the note
element integer The ID of the element
dimension_value integer The ID of the dimension value
text string The text of the note
created_time string The date and time of the note creation
user_id integer The ID of the user who created the note
username string The username of the user who created the note
display_name string The first and last name of the user who created the note
comments array The array with the note comments. 
The parameters listed below are the child notes parameters from the comments array
user_comment_id integer The ID of the note comment
scope string The type of the note
user_note_id integer The ID of the note
alert_event_id integer The ID of the alert event
notable_event_id integer The ID of the notable event
user_annotation_id integer The ID of the user annotation
text string The text of the note comment
last_updated_time string The date and time of the note comment note update
user_id integer The ID of the user who created the note comment
username integer The first and last name of the user who created the note comment
display_name integer The first and last name of the user who created the note comment

2.2. Create Note

The POST request to /api/note creates a new note.

  1. Item: note
  2. Method: POST
  3. ID: Enter the ID of an existing note
  4. Select JSON request and modify the request body by providing the following values:
    • element: The ID of the element
    • text: The text of the note
    • dimension_value: The dimension value of the element
      • Leave the value assigned to 0 if the element has no dimensions.
  5. Enter an API Token
  6. [Run request]

2.3. Edit Note

The PUT request to /api/note/id/<ID> updates the note.

  1. Item: note
  2. Method: PUT
  3. Enter the ID of the note that needs to be updated
  4. Select JSON request and provide values for the following parameters:
    • id: The ID of the note;
    • text: The new text of the note.
  5. Enter an API Token
  6. [Run request]
  7. The updated publishing_workflow_element data entry is displayed in the Raw response field

2.4. Delete Note

NOTE: Deleting a note will also delete all its note comments.

The DELETE request to /api/note/id/<ID> deletes the note.

  1. Item: note
  2. Method: DELETE
  3. ID: Enter the ID of the note that needs to be deleted
  4. Enter an API Token
  5. [Run request]

3. Configure Note Comments

3.1. Get Note Comments

The GET request to /api/note_comment returns all note comments.

  1. Item: note_comment
  2. Method: GET
  3. Optionally, filter the results:
    • ID: Return a note comment with the entered ID
    • note: Return the note comment by ID
    • element: Return all note comments related to the element with the entered ID
    • dimensions_value: Return all note comments related to the entered dimension value
  4. Enter an API Token
  5. [Run request]

Example Response 

{
  "note_comments": [
    {
      "id": 1909,
      "element": 121759,
      "dimension_value": 0,
      "note": 94,
      "user_id": 171,
      "text": "Hey, let's discuss today/tomorrow",
      "last_updated": "2022-08-04 14:46:11"
    },
    {
      "id": 1910,
      "element": 121759,
      "dimension_value": 0,
      "note": 94,
      "user_id": 139,
      "text": "What is the most common abuse reported?",
      "last_updated": "2022-08-04 14:57:49"
    },
    {
      "id": 1911,
      "element": 121759,
      "dimension_value": 0,
      "note": 94,
      "user_id": 120,
      "text": "It's in a different Report",
      "last_updated": "2022-08-04 15:11:38"
    }
  ]
}

Fields Description

Parameter Name Value Type Description
id
 integer The ID of the note comment
element integer
 The ID of the element
dimension_value integer
 The ID of the element's dimension value
note string The ID of the note
user_id integer
 The ID of the user who created the note comment
text string
 The text of the note comment
last_updated string
 The date and time when the note comment was last updated

3.2. Create Note Comment

The POST request to /api/note_comment creates a new note comment.

  1. Item: note_comment
  2. Method: POST
  3. ID: Enter the ID of an existing note comment
  4. Select JSON request and modify the request body by providing the following values:
    • text: The text of the note comment
    • id: The ID of the note
  5. Enter an API Token
  6. [Run request]

3.3. Delete Note Comment

The DELETE request to /api/note_comment/id/<ID> deletes the note comment.

  1. Item: note_comment
  2. Method: DELETE
  3. ID: Enter the ID of the note comment that needs to be deleted
  4. Enter an API Token
  5. [Run request]