NAV

mPulse Annotation API

All operations use an X-Auth-Token name/value in the request header.

Prerequisite

Follow the Authentication to get a token.

Body Parameters for the Examples

Parameter Description Optional or Required
“title” Name of the annotation Required for POST
“start” Start time of the annotation. It is a UTC time including milliseconds. Required for POST
“end” End time for annotations that have a range Optional
“text” Description of the annotation Required for POST
“domainIds” Can be a single domain ID or an array of domain IDs Optional

Add a New Annotation

Example URL

POST https://mpulse.soasta.com/concerto/mpulse/api/annotations/v1

Body

 {
   "title":"Firewall Firmware Upgrade",
   "start":1473720858000,
   "text":"Firewall upgrade started - to V2.6.8",
   "domainIds":[2603,43508]
 }

Example Response

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Date: Mon, 12 Sep 2016 23:14:14 GMT
Transfer-Encoding: chunked

{
    "id": {id}
}

Update an Annotation

Example URL

PUT https://mpulse.soasta.com/concerto/mpulse/api/annotations/v1/20601

Body

{
  "end":1473724858000,
  "text":"Firewall upgraded to V2.6.8"
}

Example Response

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Date: Tue, 13 Sep 2016 15:47:50 GMT
Transfer-Encoding: chunked

{
    "domains": [],
    "end": 1473724858000,
    "id": 20601,
    "lastModified": 1473781670085,
    "source": "REST API",
    "start": 1473720858000,
    "text": "Firewall upgraded to V2.6.8",
    "title": "Firewall Firmware Upgrade",
    "type": "USER_ENTERED",
    "user": "Wilma@abccorp.com"
}

Delete an Annotation

Example URL

DELETE https://mpulse.soasta.com/concerto/mpulse/api/annotations/v1/20601

Body

N/A

Example Response

HTTP/1.1 204 No Content
Content-Type: application/json
Date: Tue, 13 Sep 2016 16:02:54 GMT

Get an Annotation with ID 20801

Example URL

GET https://mpulse.soasta.com/concerto/mpulse/api/annotations/v1/20801

Body

N/A

Example Response

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Date: Tue, 13 Sep 2016 15:56:55 GMT
Transfer-Encoding: chunked

{
    "domains": [],
    "end": 1473724858000,
    "id": 20801,
    "lastModified": 1473781838267,
    "source": "REST API",
    "start": 1473720858000,
    "text": "Firewall upgraded to V2.6.8",
    "title": "Firewall Firmware Upgrade",
    "type": "USER_ENTERED",
    "user": "Wilma@abccorp.com"
}

Get a List of All Annotations with Optional Filters

Example URL

GET https://mpulse.soasta.com/concerto/mpulse/api/annotations/v1?date-start=1473720858000& date-end=1473720958000&domain=2603

Query Parameters:

Body

N/A

Example Response

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Date: Tue, 13 Sep 2016 15:59:13 GMT
Transfer-Encoding: chunked

[
    {
        "domains": [],
        "id": 20601,
        "lastModified": 1473722054003,
        "source": "REST API",
        "start": 1473720858000,
        "text": "Firewall upgrade started - to V2.6.8",
        "title": "Firewall Firmware Upgrade",
        "type": "USER_ENTERED",
        "user": "Wilma@abccorp.com"
    },
    {
      "domains":
      [
         {
             "id": 43508,
             "name": "ReportTestDomain"
         },
         {
             "id": 2603,
             "name": "autopartswarehouse.com"
         }
     ],
        "end": 1473724858000,
        "id": 20602,
        "lastModified": 1473781322823,
        "source": "REST API",
        "start": 1473720858000,
        "text": "Firewall upgraded to V2.6.8",
        "title": "Firewall Firmware Upgrade",
        "type": "USER_ENTERED",
        "user": "Wilma@abccorp.com"
    }
]

Errors

The Annotations API uses the following error codes:

Error Code Description
400 Bad request. The URL or JSON is invalid.
401 Unauthorized. The security token is missing or invalid.
404 Not found. The requested object does not exist.
429 The number of API requests object exceeds the rate limits.
500 Internal server error. Try again later.