Collectors API

Collector APIs have two audiences:

/api/collectors is used by administrators to register, inspect, configure, and revoke collectors. Read endpoints require infrastructure-view permission; registration, lifecycle, credential, and configuration changes require infrastructure-management permission.
/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. The console then shows separate commands to download the secrets-free installer script and run it with elevated rights plus this one-time token. It does not substitute a Docker command when a host installer is unavailable. The console also blocks registration creation, pending-token regeneration, and collector replacement until a host installer is available.

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.

Administrator endpoints​

POST /api/collectors​

Collector response fields​

PUT /api/collectors/{id}/config​

Token regeneration and revocation​

Collector endpoints​

POST /v1/collectors/enroll​

POST /v1/collectors/heartbeat​

GET /v1/collectors/config​

POST /v1/collectors/config/ack​

Poller work endpoints​

Internal notification delivery​

POST /v1/collectors/credentials/rotate​