Splunk® SOAR (On-premises)

REST API Reference for Splunk SOAR (On-premises)

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of Splunk® SOAR (On-premises). For documentation on the most recent version, go to the latest release.
Acrobat logo Download topic as PDF

REST Note

Note endpoint to consolidate the note information that exists in multiple endpoints.

/rest/note

Create a note associated with a container.

Syntax

https://<username>:<password>@<host>/rest/note

POST

Create a general note associated with a container.

Request parameters
An argument string must include the following parameters:

Field Required Type Description
container_id required integer ID of the container to add the note to.
note_format optional string Notes are displayed in either HTML or markdown. By default, note_format is set to markdown unless you pass in a different value. When you post an update of a note created before Splunk Phantom version 4.9, if you do not include the note_format as markdown, the note format defaults to HTML to maintain backwards compatibility with older notes.
title required string The title of the note.
note_type required string The type of the note: general.
content required string The content of the note.
attachments optional list of integers A list of the container attachment IDs to add to the note. A maximum of 10 attachments can be added to a note.

Example request
You can create a general note for container Id 93 by supplying a JSON formatted body.

curl -k -u admin:changeme https://localhost/rest/note \
-d '{"container_id": 93,
    "note_format": "markdown",
    "title": "something2",
    "note_type": "general",
    "content": "hello world",
    "attachments": [1, 2, 3]    
}'

Example response
A successful request returns a success indicator and the ID of the newly created note.

{
   "success": true,
    "id": 4
}

POST

Create bulk container notes.

Request parameters
An argument string must include the following parameters:

Field Required Type Description
container_id required integer Id of the container to add the note to.
phase_id optional integer If the container is a case, a phase_id can be provided to associate the note to a particular phase.
title required string The title of the note.
note_type required string The type of the note: general.
content required string The content of the note.
note_format optional string Notes are displayed in either HTML or markdown. By default, note_format is set to markdown unless you pass in a different value. When you post an update of a note created before Splunk Phantom version 4.9, if you do not include the note_format as markdown, the note format defaults to HTML to maintain backwards compatibility with older notes.

Example request
You can create many notes associated with many containers, such as multiple general notes for container Id 23, by supplying a JSON formatted body.

curl -k -u admin:changeme https://localhost/rest/note \
-d '[
    {
        "container_id": 23,
        "phase": 2,
        "title": "something2",
        "note_type": "general",
        "content": "hello world"
    },
    {
        "container_id": 23,
        "phase": 2,
        "title": "something2",
        "note_type": "general",
        "content": "hello world"
    }
]'

Example response
A successful request returns a success indicator and the IDs of the newly created notes.

[
    {
        "id": 17,
        "success": true
    },
    {
        "id": 18,
        "success": true
    }
]

POST

Create an artifact note.

Request parameters
An argument string must include the following parameters:

Field Required Type Description
container_id required integer The ID of the container.
phase_id optional integer If the container is a case, a phase_id can be provided to associate the note to a particular phase.
author_id optional integer ID of the user making the request.
title required string The title of the note.
note_type required string The type of the note: artifact.
artifact_id required string A valid artifact ID.
content required string The content of the note.

Example request
Create a note associated with an artifact by supplying a JSON formatted body with the note_type of artifact. Pass a valid artifact ID and phase ID. The container ID is set according to the artifact.

curl -k -u admin:changeme https://localhost/rest/note \
{
"container_id": 42270,
"phase_id": 1,
"author_id": 1,
"title": "my_note",
"note_type": "artifact",
"artifact_id": 155353,
"content": "hello world"
}
}'

Example response
A successful request returns a success indicator and the ID of the newly created note.

{"id": 7, "success": true}

POST

Create a task note.

Request parameters
An argument string must include the following parameters:

Field Required Type Description
title required string The title of the note.
note_type required string The type of the note: task.
task_id required integer A valid task Id.
content required string The content of the note.
note_format optional string Notes are displayed in either HTML or markdown. By default, note_format is set to markdown unless you pass in a different value. When you post an update of a note created before Splunk Phantom version 4.9, if you do not include the note_format as markdown, the note format defaults to HTML to maintain backwards compatibility with older notes.

Example request
Create a note associated with a task by supplying a JSON formatted body with the note_type of task. Pass a valid task Id. The phase is set according to the artifact.

curl -k -u admin:changeme https://localhost/rest/note \
-d '{
    "title": "my_note",
    "note_type": "task",
    "task_id":1,
    "content": "hello world"
}'

Example response
A successful request returns a success indicator and the IDs of the newly created note.

{
    "id": 24,
    "success": true
}

GET

Get a list of all notes for all items.

Example request
Get a list of notes, using paging parameters.

curl -k -u admin:changeme https://localhost/rest/note?page_size=5&page=0 -G -X GET

Example response
A successful GET will return a 200 response, and a JSON formatted list of notes.

{
        "count": 2,
        "data": [
            {
                "note_type": "general",
                "task": null,
                "container": 93,
                "title": "my note",
                "author": 1,
                "modified_time": "2019-03-26T23:50:00.451152Z",
                "content": "hello world",
                "create_time": "2019-03-26T23:50:00.384661Z",
                "artifact": null,
                "phase": 4,
                "id": 14
            },
            {
                "note_type": "general",
                "task": null,
                "container": 93,
                "title": "new note",
                "author": 1,
                "modified_time": "2019-03-27T00:16:08.220605Z",
                "content": "hello world",
                "create_time": "2019-03-27T00:14:09.090205Z",
                "artifact": null,
                "phase": 2,
                "id": 16
            }
        ],
        "num_pages": 1
    }

Example request
Return information about the note's attachments.

 /rest/note?_annotation_container_attachments

Example response
A successful return provides information about the size, name, and container attachment ID of the note.

{
'id': 144, 
'title': 'Hello World', 
'content': '<p>This is a Note </p>', 
'create_time': '2020-04-01T18:08:58.667753Z', 
'modified_time': '2020-04-01T18:08:58.673355Z', 
'note_type': 'general', 
'author': 332, 
'phase': 373, 
'container': 1148, 
'task': None, 
'artifact': None, 
'container_attachments': 
[{'container_attachment_id': 229, 'name': 'container_attachment_tGhDPDyIoOvA', 'size': 402},
 {'container_attachment_id': 230, 'name': 'container_attachment_wrQQiywwKqsj', 'size': 402}], 
'task_name': None, 
'artifact_name': None
}

/rest/note/<note_id>

List details of a single note.

Syntax

https://<username>:<password>@<host>/rest/note/<note_id>

GET

List details of a single note by ID.

Example request
List details of note Id 16.

curl -k -u admin:changeme https://localhost/rest/note/16 -G -X GET

Example response
A successful GET will return a 200 response, and a JSON formatted list of details.

{
        "note_type": "general",
        "task": null,
        "container": 93,
        "title": "new note",
        "author": 1,
        "modified_time": "2019-03-27T00:16:08.220605Z",
        "content": "hello world",
        "create_time": "2019-03-27T00:14:09.090205Z",
        "artifact": null,
        "phase": 2,
        "id": 16
    }

DELETE

Delete a note by ID.

Example request
Delete note Id 16.

curl -k -u admin:changeme https://localhost/rest/note/16 -X DELETE

Example response
A successful request will result in a 200 response returning the success message as JSON.

{
    "success": true
}

/rest/note optional filters

Filters for listing notes.

Syntax

https://<username>:<password>@<host>/rest/note?_filter_note_type

/rest/note?_filter_note_type=%22<artifact/task>%22

GET

List artifact and task notes.

Example request
List artifact notes. Notes created with /rest/artifact APIs also display in the /rest/note list views. Task notes have the associated task name in the 'artifact_name' field.

curl -k -u admin:changeme https://localhost/rest/note?_filter_note_type=%22artifact%22 -G -X GET

Example request
List task notes. Notes created with /rest/workflow_note APIs also display in the /rest/note list views. Task notes have the associated task name in the 'task_name' field

curl -k -u admin:changeme https://localhost/rest/note?_filter_note_type=%22task%22 -G -X GET

/rest/note optional query parameters

Search notes with the query parameter.

Syntax

https://<username>:<password>@<host>/rest/note?search=<search+term>

/rest/note?search=<search+term>

GET

Search notes with the query parameter.

You can search for the following:

  • Note title
  • Note content
  • Task name for task notes
  • Artifact name for artifact notes
  • Artifact Id for artifact notes

Examples, using container_id=15: /rest/note?_filter_container_id=15&search=note+title /rest/note?_filter_container_id=15&search=note+description /rest/note?_filter_container_id=15&search=artifact+title /rest/note?_filter_container_id=15&search=task+title /rest/note?_filter_container_id=15&search=43

Example request
Search notes with the query parameter for "gorilla" and using container_id=15.

curl -k -u admin:changeme https://localhost/rest/note?_filter_container_id=15&search=gorilla -G -X GET

Example response
A successful request returns a success indicator and the items containing gorilla.

{
  "count": 1,
  "data": [
      {
          "artifact_name": null,
          "note_type": "task",
          "task": 4,
          "container": 15,
          "title": "Assigned to MgGilla.",
          "author": 1,
          "modified_time": "2019-05-16T17:09:00.437518Z",
          "content": "<p>This is a good case for the Gorilla!</p>",
          "create_time": "2019-05-16T17:09:00.428279Z",
          "artifact": null,
          "task_name": "Report incident response execution",
          "phase": 1,
          "id": 1
      }
  ],
  "num_pages": 1
}
Last modified on 08 March, 2023
PREVIOUS
REST Tenant
  NEXT
REST Notification

This documentation applies to the following versions of Splunk® SOAR (On-premises): 5.1.0, 5.2.1, 5.3.1, 5.3.2, 5.3.3, 5.3.4, 5.3.5, 5.3.6, 5.4.0, 5.5.0


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters