API Overview

The Lumetry API is an HTTP/JSON API. This page covers the conventions that apply to every endpoint: base URLs, authentication, identifiers, permissions, status codes, and the error shape. Read it once; the per-resource pages assume it.

Base URL and API surfaces

There are two route families:

Prefix	Purpose	Audience
/v1/...	Stable, machine-to-machine integration endpoints for metric ingestion, external alert webhooks, collectors, and CMDB topology push.	External systems, collectors, and automation.
/api/...	Resource endpoints for rules, alerts, incidents, catalog, topology, collectors, access, and API tokens.	The Lumetry console, operators, and trusted automation.

All examples use http://localhost:8080 as the host; substitute your deployment's base URL.

Authentication

Every API request requires authentication via a Bearer token in the Authorization header, unless an endpoint is explicitly documented as public:

Authorization: Bearer {token}

There are four token types:

• Interactive access tokens — short-lived tokens used by signed-in console users.
• API tokens — long-lived, opaque Bearer tokens created from the console for automation and integrations.
• Collector credentials — dedicated machine credentials issued during collector enrollment. They can call collector endpoints and metric ingestion, not general user-facing APIs.
• External alert source credentials — dedicated credentials returned when an external alert source is created or rotated. Each credential can call only its source webhook.

See Authentication & Tokens. Machine integrations such as ingestion and CMDB sync should use an API token.

Identifiers

Lumetry uses three kinds of identifier. Mixing them up is the most common integration mistake:

• Resource integer IDs. Rules, alerts, incidents, topology nodes, metric sources, users, integrations, and metric definitions are identified by integer id. Unless a route says otherwise, {id} is one of these.
• Source-facing string keys. A metric key (also called metricId in many payloads) is a string, because it must match the metric name in the metric store and in your data pipelines. Routes such as GET /api/metrics/{id}/series and POST /api/metric-definitions/{metricKey}/bindings use the string key, not a numeric ID.
• Collector UUIDs. Collector routes use UUID strings such as d97e2b99-81bd-43aa-823d-dc5f78cd5429.

Each endpoint page states which kind it expects.

Permissions

Access is governed by role-derived permissions. The ones you'll meet:

Permission	Grants
CanViewAlerts	Read access to metrics, rules, alerts, violations, incidents, topology, catalog, sources, system alerts.
CanManageRules	Write access to rules, metric definitions, metric sources, topology (including CMDB push), and bindings.
CanIngestMetrics	Pushing metric points via the ingestion endpoints.
CanManageUsers	User and role management.
CanManageIntegrations	Collector and notification-integration management.
CanManageAlertProfiles	Notification routing-profile management.
CanAcknowledgeAlerts	Acknowledge alerts and incidents.
CanCloseAlerts	Close alerts and resolve incidents.
CanViewAuditLogs	Audit log access.

API-token requests act with the owner user's permissions, with one exception: an API-token request cannot create or revoke API tokens (that is interactive-only).

Status codes

Code	Meaning in Lumetry
200 OK	Successful read or update.
201 Created	A resource was created; the body is the new resource.
202 Accepted	The request was durably accepted for asynchronous processing (for example ingestion).
400 Bad Request	Validation failed. The body is an error object. No partial writes occur.
401 Unauthorized	Missing or invalid token.
403 Forbidden	Authenticated but lacking the required permission.
404 Not Found	No such resource.
429 Too Many Requests	Rate limit exceeded. Use the Retry-After header before retrying.

Error shape

Validation and domain errors return a problem-details style JSON object. Some endpoints add a structured errors array:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Topology import payload validation failed.",
  "errors": [
    { "path": "edges[0]", "message": "Edge not allowed: a 'Host' cannot 'runs_on' a 'Component'." }
  ]
}

When an errors array is present, nothing was written — these endpoints validate the whole payload before applying any of it.

Older clients may still see a simple message or error field from a few compatibility surfaces. New integrations should read detail first, then fall back to title, message, or error.

Asynchronous semantics

Ingestion is decoupled from evaluation. An accepted metric or external alert transition returns 202 immediately and is processed later — a 202 means durably queued, not already evaluated or correlated. Do not expect an alert to exist the instant ingestion returns.