Collectors API

Collector APIs have two audiences:

• /api/collectors is used by administrators to register, inspect, configure, and revoke collectors. These endpoints require CanManageInfrastructure.
• /v1/collectors/* is used by collector processes. Enrollment uses a one-time token; later requests use the collector credential returned by enrollment.

Collector IDs are UUID strings, not integer resource IDs.

Administrator endpoints

Method & path	Purpose
GET /api/collectors	List collector registrations and health state.
GET /api/collectors/{id}	Get one collector and its desired configuration.
POST /api/collectors	Create a pending registration and one-time enrollment token.
POST /api/collectors/{id}/enrollment-token	Replace the token for a collector that has never enrolled.
PUT /api/collectors/{id}/config	Replace the desired configuration and increment its revision.
POST /api/collectors/{id}/revoke	Revoke the collector and all active credentials.

POST /api/collectors

{
  "name": "payments-host-01"
}

Response 201

{
  "id": "d97e2b99-81bd-43aa-823d-dc5f78cd5429",
  "name": "payments-host-01",
  "enrollmentToken": "lmte_...",
  "enrollmentExpiresAt": "2026-06-14T09:00:00Z"
}

The plaintext enrollment token is returned only when the registration is created or the unused token is regenerated. Store or pass it to the target host immediately.

Collector response fields

List and mutation responses use the following operational fields:

Field	Meaning
id	Collector UUID.
status	pending, active, duplicate_suspected, or revoked.
enrolledAt, lastSeenAt	Enrollment and latest successful heartbeat times.
version	Version last reported by the collector.
configRevision	Desired configuration revision.
configRevisionApplied	Revision last reported as applied or rejected.
configApplyStatus, configApplyError	Latest configuration acknowledgement.
queueDepth, droppedCount	Local buffering health reported by heartbeat.
clockSkewMs	Difference between collector and server time.
createdBy	Numeric user ID that created the registration, or null for a system-created record.

GET /api/collectors/{id} returns:

{
  "collector": {
    "id": "d97e2b99-81bd-43aa-823d-dc5f78cd5429",
    "name": "payments-host-01",
    "status": "active",
    "configRevision": 3,
    "configRevisionApplied": 3,
    "queueDepth": 0,
    "droppedCount": 0
  },
  "config": {
    "hostMetrics": {
      "enabled": true,
      "intervalSeconds": 60
    }
  }
}

PUT /api/collectors/{id}/config

The config value must be a JSON object.

{
  "config": {
    "hostMetrics": {
      "enabled": true,
      "intervalSeconds": 30
    }
  }
}

Saving replaces the desired document and increments configRevision. The collector later reports whether it applied or rejected that revision.

Token regeneration and revocation

POST /api/collectors/{id}/enrollment-token succeeds only while the collector is still pending. It returns the same response shape as collector creation.

POST /api/collectors/{id}/revoke invalidates active collector credentials and returns the updated collector. A revoked identity cannot be reactivated.

Collector endpoints

POST /v1/collectors/enroll

Enrollment is the only collector endpoint that does not use an Authorization header. The one-time token in the request is the credential.

{
  "token": "lmte_...",
  "hostFacts": {
    "hostname": "payments-host-01",
    "os": "Linux",
    "version": "1.0.0",
    "machineFingerprint": "a stable hashed host identifier"
  }
}

Response 200

{
  "collectorId": "d97e2b99-81bd-43aa-823d-dc5f78cd5429",
  "collectorToken": "lmtc_...",
  "expiresAt": "2026-12-08T09:00:00Z",
  "configRevision": 1
}

Unknown, expired, already-used, or otherwise invalid enrollment tokens all return the same generic 401 Unauthorized response.

Use the returned credential for all later collector calls:

Authorization: Bearer lmtc_...

The same credential can send metric batches to POST /v1/metrics.

POST /v1/collectors/heartbeat

{
  "instanceId": "4f4219dd-a42f-4f5b-972a-9f81929bb69f",
  "machineFingerprint": "a stable hashed host identifier",
  "seq": 42,
  "startedAt": "2026-06-11T08:00:00Z",
  "version": "1.0.0",
  "configRevisionApplied": 3,
  "queueDepth": 18,
  "droppedCount": 0,
  "oldestQueuedAt": "2026-06-11T08:58:00Z",
  "localTime": "2026-06-11T09:00:00Z"
}

Response 200

{
  "configRevisionAvailable": 3,
  "rotateRequired": false,
  "versionStatus": "ok"
}

versionStatus is ok, outdated, or unsupported.

GET /v1/collectors/config

Returns the desired configuration:

{
  "revision": 3,
  "config": {
    "hostMetrics": {
      "enabled": true,
      "intervalSeconds": 60
    }
  }
}

The response includes ETag: "3". Send If-None-Match: "3" on the next request; the server returns 304 Not Modified when the revision has not changed.

POST /v1/collectors/config/ack

{
  "revision": 3,
  "status": "applied",
  "error": null
}

status is applied or rejected. For a rejected revision, provide a useful error message. Success returns 204 No Content.

Poller work endpoints

The following endpoints require the collector's current poller capability. An authenticated collector without that capability receives 403 Forbidden.

GET /v1/collectors/poller-plan returns the enabled metric sources assigned to the collector. POST /v1/collectors/source-health reports their latest collection outcome.

GET /v1/collectors/source-tests atomically claims interactive connection/query tests:

{
  "tests": [
    {
      "testId": "f449b8ca-cd8a-4149-9a6b-d87235682d10",
      "claimToken": "7ee7c9d9-a933-46c6-91d9-a012322eb87c",
      "leaseExpiresAt": "2026-06-23T10:05:00Z",
      "sourceId": 12,
      "sourceType": "PROMETHEUS",
      "connectionConfig": "{\"baseUrl\":\"http://prometheus.internal:9090\"}",
      "sealedCredential": null,
      "kind": "connection",
      "query": null
    }
  ],
  "executionTimeoutSeconds": 30
}

Report the result to POST /v1/collectors/source-tests/{testId}/result and echo the claim token. A stale token returns 409 Conflict; the collector must discard that result.

Internal notification delivery

A collector with the delivery capability claims internal-target webhook work through GET /v1/collectors/deliveries:

{
  "deliveries": [
    {
      "deliveryId": 481,
      "claimToken": "a12d1bea-a280-48fa-ac40-df9ef06550be",
      "leaseExpiresAt": "2026-06-23T10:06:00Z",
      "type": "Webhook",
      "endpointUrl": "https://alerts.internal/hooks/lumetry",
      "headers": {},
      "payloadJson": "{...}"
    }
  ],
  "executionTimeoutSeconds": 30
}

Report completion to POST /v1/collectors/deliveries/{deliveryId}/result with { claimToken, success, error? }. A stale/reassigned claim returns 409 Conflict. The collector must finish within the supplied lease and must not retry a rejected stale result.

POST /v1/collectors/credentials/rotate

Returns a replacement collector credential:

{
  "collectorToken": "lmtc_...",
  "expiresAt": "2026-12-08T09:00:00Z"
}

Persist the replacement before switching credentials. The previous credential remains valid only for a short grace period.