/api/annotation/bulk

NOTE: (Version 2.1) The bulk endpoint enables adding, updating or deleting multiple annotations in a single call. Annotation updates must be sent over PUT or POST as content data. Query string requests are not supported for POST or GET. Each annotation is processed individually and synchronized with the backend. If one of the annotations has an error, such as a missing field, an exception will be returned and some of the annotations may not be written to storage. In such an event, the errant annotation should be fixed and all annotations sent again.

Annotations may also be deleted in bulk for a specified time span. If you supply a list of of one or more TSUIDs, annotations with a start time that falls within the specified timespan and belong to those TSUIDs will be removed. Alternatively the global flag can be set and any global annotations (those not associated with a time series) will be deleted within the range.

Verbs

  • POST - Create or modify annotations
  • PUT - Create or replace annotations
  • DELETE - Delete annotations within a time range

Requests

Fields for posting or updating annotations are documented at /api/annotation

Fields for a bulk delete request are defined below:

Name Data Type Required Description Default QS RW Example
startTime Integer Required A timestamp for the start of the request. The timestamp may be relative or absolute as per Dates and Times. start_time RO 1369141261
endTime Integer Optional An optional end time for the event if it has completed or been resolved. The timestamp may be relative or absolute as per Dates and Times. end_time RO 1369141262
tsuids Array Optional A list of TSUIDs with annotations that should be deleted. This may be empty or null (for JSON) in which case the global flag should be set. When using the query string, separate TSUIDs with commas. tsuids RO 000001000001000001, 000001000001000002
global Boolean Optional Whether or not global annotations should be deleted for the range false global RO true

Warning

If your request uses PUT, any fields that you do not supply with the request will be overwritten with their default values. For example, the description field will be set to an empty string and the custom field will be reset to null.

Example POST/PUT Request

[
  {
  "startTime":"1369141261",
  "tsuid":"000001000001000001",
  "description": "Testing Annotations",
  "notes": "These would be details about the event, the description is just a summary",
  "custom": {
    "owner": "jdoe",
    "dept": "ops"
  }
  },
  {
  "startTime":"1369141261",
  "tsuid":"000001000001000002",
  "description": "Second annotation on different TSUID",
  "notes": "Additional details"
  }
]

Example DELETE QS Request

/api/annotation/bulk?start_time=1d-ago&end_time=1h-ago&method_override=delete&tsuids=000001000001000001,000001000001000002

Example DELETE Request

{
  "tsuids": [
    "000001000001000001",
    "000001000001000002"
  ],
  "global": false,
  "startTime": 1389740544690,
  "endTime": 1389823344698,
  "totalDeleted": 0
}

Response

A successful response to a POST or PUT request will return the list of annotations after synchronization (i.e. if issuing a POST call, existing objects will be merged with the new objects). Delete requests will return an object with the delete query and a totalDeleted field with an integer number reflecting the total number of annotations deleted. If invalid data was supplied a 400 error will be returned along with the specific annotation that caused the error in the details field of the error object.

Example POST/PUT Response

[
  {
    "tsuid": "000001000001000001",
    "description": "Testing Annotations",
    "notes": "These would be details about the event, the description is just a summary",
    "custom": {
      "owner": "jdoe",
      "dept": "ops"
    },
    "endTime": 0,
    "startTime": 1369141261
  },
  {
    "tsuid": "000001000001000002",
    "description": "Second annotation on different TSUID",
    "notes": "Additional details",
    "custom": null,
    "endTime": 0,
    "startTime": 1369141261
  }
]

Example DELETE Response

{
  "tsuids": [
    "000001000001000001",
    "000001000001000002"
  ],
  "global": false,
  "startTime": 1389740544690,
  "endTime": 1389823344698,
  "totalDeleted": 42
}

© 2010–2016 The OpenTSDB Authors
Licensed under the GNU LGPLv2.1+ and GPLv3+ licenses.
http://opentsdb.net/docs/build/html/api_http/annotation/bulk.html