Agents¶

POST /v1/agents/register¶

Register an agent with the Noctuary backend. Call this once on agent startup before sending events. If the agent restarts, calling register again updates its hostname and version (idempotent).

Requires an ingest API key.

curl -X POST https://api.noctuary.io/v1/agents/register \
  -H "Authorization: Bearer noc_ingest_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "prod-k8s-node-01",
    "name": "production-cluster",
    "version": "0.1.0"
  }'

Response: 201 Created

{
  "id": "b569e0bd-0f06-45f5-b761-8f5340692453",
  "tenant_id": "5f0bfa6c-c977-43ea-94e2-1b305c643b0a",
  "api_key_id": "72a61fcd-e752-4d0d-91d4-bbf1dd5687c4",
  "hostname": "prod-k8s-node-01",
  "name": "production-cluster",
  "agent_version": "0.1.0",
  "registered_at": "2026-05-31T12:00:55Z",
  "last_seen_at": "2026-05-31T12:00:55Z"
}

Request body¶

Field	Type	Required	Description
`hostname`	string	Yes	Hostname of the machine running the agent
`name`	string	No	Human-readable name (shown in dashboard). Falls back to hostname.
`version`	string	No	Agent version string

POST /v1/agents/{id}/heartbeat¶

Update the agent's last_seen_at timestamp without sending an event. Used by agents when no log activity has been detected for a period.

Requires an ingest API key.

curl -X POST https://api.noctuary.io/v1/agents/{id}/heartbeat \
  -H "Authorization: Bearer noc_ingest_your_key"

Response: 204 No Content

Note

Every successful event ingest also counts as a heartbeat, so agents processing active log streams do not need to call this endpoint separately.

GET /v1/agents¶

List all registered agents for your account.

curl https://api.noctuary.io/v1/agents \
  -H "Authorization: Bearer noc_ro_your_key"

Response: 200 OK

[
  {
    "id": "b569e0bd-0f06-45f5-b761-8f5340692453",
    "hostname": "prod-k8s-node-01",
    "name": "production-cluster",
    "agent_version": "0.1.0",
    "registered_at": "2026-05-31T12:00:55Z",
    "last_seen_at": "2026-05-31T12:01:23Z",
    "events_last_hour": 142
  }
]

GET /v1/agents/{id}¶

Get a specific agent and its paginated event log.

curl "https://api.noctuary.io/v1/agents/{id}?per_page=20&page=1" \
  -H "Authorization: Bearer noc_ro_your_key"

Query parameters¶

Parameter	Values	Default	Description
`per_page`	10, 20, 50, 100	10	Events per page
`page`	integer	1	Page number
`service`	string	—	Filter by service name
`vendor`	string	—	Filter by vendor
`event_type`	string	—	Filter by event type

Response: 200 OK

{
  "agent": { ... },
  "events": [ ... ],
  "page": 1,
  "per_page": 20,
  "total_pages": 5,
  "total": 98,
  "filter_services": ["payments-api", "auth-service"],
  "filter_vendors": ["argocd", "kubernetes"],
  "filter_service": null,
  "filter_vendor": null,
  "filter_event_type": null
}