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.
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.
[
{
"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"
}
]
/api/annotation/bulk?start_time=1d-ago&end_time=1h-ago&method_override=delete&tsuids=000001000001000001,000001000001000002
{
"tsuids": [
"000001000001000001",
"000001000001000002"
],
"global": false,
"startTime": 1389740544690,
"endTime": 1389823344698,
"totalDeleted": 0
}
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.
[
{
"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
}
]
{
"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