Annotations

The annotations API call can be used to query a CloudShark system and obtain all annotations associated with a specific capture file. It is also able to add annotations to individual packets within a capture file.

In order to set annotations, the API Token must have permission to add them.

Listing Annotations

GET /api/v1/<token>/annotations/<cid>

The annotation call can be invoked by sending an http or https GET request to the CloudShark system using a valid API token and CloudShark session capture ID.

The method returns a JSON array containing all of the annotations, each in their own object:

[
 {
  "line": 3,
  "capture_id": "cd17d8b73fea",
  "text": "this is an annotation",
  "user": "admin"
 },
 {
  "line": 7,
  "capture_id": "cd17d8b73fea",
  "text": "here is another annotation",
  "user": "admin"
 }
]

Adding Annotations

By sending a POST request to the same endpoint, the API can be used to write annotations on individual packets within a specific capture file.

POST /api/v1/<token>/annotations/<cid>?frame=5&text=My+Annotation

If you would like to remove an annotation, send a POST with only the frame parameter set.

Note: Adding more than one annotation needs to be done through multiple calls to the API. This API currently only supports one annotation at a time.

Suppressing Output

If you do not need all of the annotations returned following the addition of a new one, CloudShark can be sent the quiet parameter and will return only a 204 No Content HTTP response upon success. This can speed up API requests when there are many annotations on a single file.

Example using Curl curl

curl -X POST https://www.cloudshark.org/api/v1/[token]/annotations/42b902afcdee \
   --data "frame=5" \
   --data "text=Take a look at this frame for issues"

This method will return all the annotations found in the given capture with your latest changes applied. Exactly the same output as the GET version of the call.

[
 {
  "line": 3,
  "capture_id": "cd17d8b73fea",
  "text": "this is an annotation",
  "user": "admin"
 },
 {
  "line": 5,
  "capture_id": "cd17d8b73fea",
  "text": "Take a look at this frame for issues",
  "user": "admin"
  },
 {
  "line": 7,
  "capture_id": "cd17d8b73fea",
  "text": "here is another annotation",
  "user": "admin"
 }
]