# API reference

> The Telemetry Machine REST API, with its base URL, credentials, responses and errors.

The Telemetry Machine API is organized around the resources of your organization. It takes JSON request bodies, returns JSON, and uses standard HTTP status codes. Each resource's page describes its object and its endpoints:

- [Annotations](https://telemetrymachine.com/docs/api/annotations): deploys, changes and comments, drawn on your charts.
- [CI trust rules](https://telemetrymachine.com/docs/api/ci-trust-rules): the repositories whose CI jobs may post annotations without a stored secret.

To do something, rather than look up a field, start from a guide, such as [Annotations](https://telemetrymachine.com/docs/annotations). Telemetry goes over OTLP, not through this API (refer to [Send OpenTelemetry](https://telemetrymachine.com/docs/send-opentelemetry)), and events go to [JSON events](https://telemetrymachine.com/docs/json-events).

## Base URL

```plaintext
https://telemetrymachine.com/api/organizations/{org}
```

`{org}` is your organization's slug, the part after `telemetrymachine.com/` when you're signed in. A credential works only in its own organization.

## Authentication

| Credential                           | Send it as                    | It may                                                                                    |
| ------------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------- |
| A personal access token              | `Authorization: Bearer TOKEN` | Do what you can do in the console, within the scopes that you gave it                     |
| An OAuth sign-in, such as an agent's | `Authorization: Bearer TOKEN` | The same, within the scopes that you granted                                              |
| An ingest key                        | `X-API-Key: KEY`              | Send data, and post annotations once its annotate setting is on                           |
| A CI job's OIDC token                | `Authorization: Bearer TOKEN` | Post annotations, from a repository that a [trust rule](https://telemetrymachine.com/docs/api/ci-trust-rules) lets in |

Create a personal access token in **Settings → Personal tokens**. Each endpoint says which credentials it takes, and which scope a token needs.

## Responses

A response wraps its result in an envelope, with the result in `data`:

```json status="200" title="Response"
{
  "status": 200,
  "data": {
    "public_id": "ann_01m5x9q2r7t4k8w3e6y1p0z5ab",
    "type": "deploy",
    "message": "checkout 1.42.0"
  }
}
```

A list puts its items in `data` under the resource's plural name, such as `annotations`. Times are RFC 3339 in UTC, such as `2026-10-26T13:50:04.000Z`. Send times with a zone.

## Errors

A failed request gets a 4xx or 5xx status, and a body that says why:

```json status="400" title="Response"
{
  "statusCode": 400,
  "message": ["type must be one of deploy, change, comment"],
  "error": "Bad Request"
}
```

`message` is a list when the body fails validation, and a string otherwise. A field that an endpoint doesn't take is refused with 400, so a misspelled field name never passes silently.

| Status | Means                                                            |
| ------ | ---------------------------------------------------------------- |
| 400    | The request is invalid. `message` says what to fix.              |
| 401    | The credential is missing, unknown or expired.                   |
| 403    | The credential can't do this, such as a token without the scope. |
| 404    | The organization has no such resource, or you can't read it.     |
| 409    | The request conflicts with what exists, such as a reused key.    |
| 429    | A limit is used up. The resource's page says which.              |

---

All pages: https://telemetrymachine.com/docs/llms.txt