API Endpoints for SLO Annotations
Using Nobl9 REST API users can create new Annotations, fetch existing ones, or delete them.
Nobl9 API has been designed to make it convenient for admins to programmatically connect their tools (e.g. for CI/CD) to Nobl9 and automate annotating SLOs (for example, during deployments). Itβs a standard REST API with GET
, POST
, PUT
, and DELETE
commands available for use.
Common headersβ
Header | Description |
---|---|
Accept |
|
Organization |
|
Project |
|
Authorization |
|
Access Tokenβ
The Nobl9 API endpoint for SLO Annotations requires an access token. This enables you to secure your web server's URLs so that only you and Nobl9 have access to them. The access token consists of your Client ID and Client Secret. For details on how to generate your credentials, go here.
Generate Access Tokenβ
POST /api/accessToken
Example request:
curl -X POST https://app.nobl9.com/api/accessToken -H 'Accept: application/json; version=v1alpha' -H 'Organization: nobl9-dev' -H "Authorization: Basic ${encoded_access_keys}"
Headers
Header Mandatory? Accept
No Authorization
Yes.
Use the following syntax:
Basic base64enc(${clientId}:${clientSecret}).
Organization
Yes tip
We recommend downloading your token once and reusing it in your CI/CD pipeline. Generating multiple tokens may exceed your rate limits. For more details, refer to the Rate Limits section.
Annotationsβ
Get Annotationsβ
Fetch Annotations that have the values specified in a request.
GET /api/annotations
Example request:
curl -X GET https://app.nobl9.com/api/annotations?from=2021-12-07T08:00:00Z&to=2021-12-08T13:00:00Z&name=my-annotation-1&name=my-annotation-2&slo=my-slo' -H 'Accept: application/json; version=v1alpha' -H 'Organization: nobl9-dev' -H 'Project: *' -H "Authorization: Bearer ${access_token}"
Example response:
[
{
"name": "my-annotation-1",
"project": "my-project-2",
"slo": "my-slo",
"description": "this is my first annotation",
"startTime": "2021-12-08T12:20:00Z",
"endTime": "2021-12-08T12:20:00Z",
"status": {
"updatedAt": "2021-12-09T16:36:35.298419Z"
}
},
{
"name": "my-annotation-1",
"project": "my-project-2",
"slo": "my-slo",
"description": "this is my second annotation",
"startTime": "2021-12-08T12:30:00Z",
"endTime": "2021-12-08T12:30:00Z",
"status": {
"updatedAt": "2021-12-10T12:54:48.93971Z"
}
}
]Parameters:
Parameter Description slo
The name of the SLO to which the annotations are attached. name
- The name of the annotation.
- You can provide multiple names.
- The query matches all the names, just as in the example above (
name=my-annotation-1&name=my-annotation-2
).
from
Start time of the Annotation period in RFC3339 format. to
End time of the Annotation period in RFC3339 format. Headers:
Header Mandatory? Accept
No Authorization
Yes Organization
Yes Project
Yes
Create Annotationsβ
Create a new Annotation for any event within one of your SLOs.
POST /api/annotations
Example request:
curl -X POST https://app.nobl9.com/api/annotations -H 'Accept: application/json; version=v1alpha' -H 'Organization: my-org' -H "Authorization: Bearer ${access_token}" -d "@create.json"
Example body:
{
"name": "my-annotation",
"project": "my-project",
"slo": "my-slo",
"description": "this is my annotation",
"startTime": "2021-12-08T12:20:00Z",
"endTime": "2021-12-08T12:20:00Z"
}Parameters:
Parameter Description slo
The name of the SLO to which the annotations are attached. project
String, must conform to DNS (RFC 1123 format). name
- The name of the annotation.
- You can provide multiple names.
- The query matches all the names, just as in the example above (
name=my-annotation-1&name=my-annotation-2
).
from
Start time of the Annotation period in RFC3339 format. to
End time of the Annotation period in RFC3339 format. Example response:
{
"name": "my-annotation",
"project": "my-project",
"slo": "my-slo",
"description": "this is my annotation",
"startTime": "2021-12-08T12:20:00Z",
"endTime": "2021-12-08T12:20:00Z",
"status": {
"updatedAt": "2021-12-09T16:36:35.298419Z"
}
}Headers:
Header Mandatory? Accept
No Authorization
Yes Organization
Yes
Update Annotationsβ
You can update Annotations using a standard PUT
request. This method will create a new annotation unless the annotation with the provided name (i.e. specified in the body of the JSON object) does not exist in the specified Project.
In addition, you must also provide all the remaining parameters even if you want to update just one of them (effectively, this command acts like a REPLACE
command).
PUT /api/annotations/{name}
Example request:
curl -X PUT https://app.nobl9.com/api/annotations/my-annotation -H 'Accept: application/json; version=v1alpha' -H 'Organization: my-org' -H "Authorization: Bearer ${access_token}"
Example body:
{
"project": "my-project",
"slo": "my-slo",
"description": "this is my annotation",
"startTime": "2021-12-08T12:20:00Z",
"endTime": "2021-12-08T12:20:00Z"
}Parameters:
Object Mandatory? Description project
Yes String, must conform to DNS (RFC 1123 format). slo
Yes The name of the SLO to which the Annotation is attached. description
Yes String, can contain up to 1000 characters. startTime
Yes Start time of the Annotation period in RFC3339 format. endTime
Yes End time of the Annotation period in RFC3339 format. Example response:
{
"name": "my-annotation",
"project": "my-project",
"slo": "my-slo",
"description": "this is my annotation",
"startTime": "2021-12-08T12:20:00Z",
"endTime": "2021-12-08T12:20:00Z",
"status": {
"updatedAt": "2021-12-09T16:36:35.298419Z"
}
}Headers:
Header Mandatory? Accept
No Authorization
Yes Organization
Yes
Remove Annotationsβ
DELETE /api/annotations/{name}
Example request:
curl -X DELETE https://app.nobl9.com/api/annotations/my-annotation -H 'Accept: application/json; version=v1alpha' -H 'Organization: my-org' -H 'Project: my-project' -H "Authorization: Bearer ${access_token}"
Headers:
Header Mandatory? Accept
No Authorization
Yes Organization
Yes Project
Yes
Annotations Quota and Rate Limitsβ
A quota limits the number of Annotations - there is a limit of 100 000 annotations per organization.
All requests to the endpoint https://app.nobl9.com/api/accessToken
are rate limited. An organization can make 10 requests per minute - 1 request per 6 seconds. The API returns the 429 HTTP
status code when this limit is exceeded.