Skip to main content
API docs by Redocly

Nobl9 Annotations API (v1alpha)

Using Nobl9 Annotations API, you can create annotations, fetch existing ones, or delete them.

Annotations quota and rate limits

A quota limits the number of user annotations to 100 000 annotations per organization.

For rate limits, see the Rate limits section below.

Scroll down to see code samples

Access Token

Generate access token

To generate access token, you must provide Authorization header with the Basic scheme.

The access token consists of your Client ID and Client Secret in the following format: clientId:clientSecret.

Rate Limits for access token

All requests to the endpoint /api/accessToken are rate limited. An organization can make 1 request per 3 seconds.

The API returns the 429 HTTP status code when this limit is exceeded.

NOTE
Your token will be valid for 1 hour. Minimize the usage of this endpoint and reuse the token until it expires.

We recommend downloading your token once and reusing it in your CI/CD pipeline. Generating multiple tokens may exceed your rate limits.

Authorizations:
basicAuth
header Parameters
Organization
required
string

Your organization ID. You can find it in the Nobl9 UI, in the Settings > Account.

Responses

Request samples 

curl -X \
POST https://app.nobl9.com/api/accessToken -H 'Accept: application/json; version=v1alpha' \
-H 'Organization: your-organization-id' \
-H 'Authorization: Basic ${encoded_access_keys}'

Response samples

Content type
application/json
{
  • "access_token": "string"
}

Annotations

Get the list of annotations

Get annotations with the values specified in a request.

Authorizations:
bearerAuth
query Parameters
name
Array of strings

The name of the annotation. You can provide multiple names. The query matches all the names.

slo
string

The name of the annotated SLO.

from
string <date-time>
Example: from=2025-08-07T08:00:00Z

Matches Annotation.startTime. Start time of the annotation period in RFC3339 format.

to
string <date-time>
Example: to=2025-08-07T09:00:00Z

Matches Annotation.endTime. End time of the annotation period in RFC3339 format.

category
string
Enum: "Adjustment" "Alert" "NoDataAnomaly" "User"

The type of annotation to filter by. You can provide multiple values. Must be one of:

  • Adjustment—System-generated annotations for budget adjustments
  • Alert—System-generated annotations for SLO alerts
  • NoDataAnomaly—System-generated annotations for no data anomalies
  • User—User-created annotations
header Parameters
Organization
required
string

Your organization ID. You can find it in the Nobl9 UI, in the Settings > Account.

Project
required
string

Project name, must conform to DNS (RFC 1123 format). might be wildcard with *.

Responses

Request samples 

curl -X \
GET https://app.nobl9.com/api/annotations?from=2025-08-07T08:00:00Z&to=2025-08-08T13:00:00Z&name=my-annotation-1&name=my-annotation-2&slo=my-slo' -H 'Accept: application/json; version=v1alpha' \
-H 'Organization: your-organization-id' \
-H 'Project: *' \
-H 'Authorization: Bearer ${access_token}'

Response samples

Content type
application/json
[
  • {
    }
]

Create single annotation

Create an annotation for any event happened to your SLO.

Authorizations:
bearerAuth
header Parameters
Organization
required
string

Your organization ID. You can find it in the Nobl9 UI, in the Settings > Account.

Request Body schema: application/json
required

JSON object keys

description
required
string <= 1000 characters
endTime
required
string <date-time>

End time of the annotation period in RFC3339 format.

name
required
string

The name of the annotation.

project
required
string

Must conform to DNS (RFC 1123 format).

slo
required
string

The name of the SLO to which the annotation is attached.

startTime
required
string <date-time>

Start time of the annotation period in RFC3339 format.

object

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "endTime": "2025-08-07T18:04:05Z",
  • "name": "name",
  • "project": "default",
  • "slo": "my-slo-name",
  • "startTime": "2025-08-07T08:04:05Z",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "name": "my-annotation-name",
  • "project": "default",
  • "slo": "my-slo-name",
  • "startTime": "2025-08-07T08:04:05Z",
  • "endTime": "2025-08-07T18:04:05Z",
  • "status": {
    },
  • "category": "Alert",
  • "labels": {
    }
}

Delete single annotation

This endpoint deletes the annotation with the given name in the specified project (Project header).

You must provide explicit project name, not wildcard.

NOTE
Only Organization Admins can delete system annotations, for example, when a false alert was triggered. Users with other permissions can only view system annotations.

Authorizations:
bearerAuth
path Parameters
name
required
string

Annotation name

header Parameters
Organization
required
string

Your organization ID. You can find it in the Nobl9 UI, in the Settings > Account.

Project
required
string

Project name, must be explicit, wildcard is not supported

Responses

Request samples 

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}'

Upsert single annotation

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).

Authorizations:
bearerAuth
path Parameters
name
required
string

Annotation name

header Parameters
Organization
required
string

Your organization ID. You can find it in the Nobl9 UI, in the Settings > Account.

Request Body schema: application/json
required

Annotations' details

description
required
string <= 1000 characters
endTime
required
string <date-time>

End time of the annotation period in RFC3339 format.

project
required
string

String, must conform to DNS (RFC 1123 format).

slo
required
string

The name of the SLO to which the annotation is attached.

startTime
required
string <date-time>

Start time of the annotation period in RFC3339 format.

object

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "endTime": "2025-08-07T18:04:05Z",
  • "project": "default",
  • "slo": "my-slo-name",
  • "startTime": "2025-08-07T08:04:05Z",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "name": "my-annotation-name",
  • "project": "default",
  • "slo": "my-slo-name",
  • "startTime": "2025-08-07T08:04:05Z",
  • "endTime": "2025-08-07T18:04:05Z",
  • "status": {
    },
  • "category": "Alert",
  • "labels": {
    }
}