Collector API v1 reference

Overview

The v0.1 collector talks to three POST, JSON, snake_case endpoints under /api/v1/collectors. On deployments where the main site is access-restricted, identical mirrors are also exposed under /api/public/v1/collectors so a collector on an unauthenticated network path can still reach the control plane.

Authentication and tokens

Enrollment tokens are random, short-lived, single-use, and bound to a specific partner, customer and site at issue time. The control plane stores only a SHA-256 hash of the token, never the token itself, and invalidates it atomically on successful enrollment so it can never be replayed.

Heartbeat and observations calls authenticate with a bearer token issued at enrollment.

Authorization: Bearer <auth_token>

Enroll

Called once, on first start, to exchange the one-time enrollment token for a durable collector identity.

{
  "token": "<one-time-token>",
  "hostname": "web-scanner-01",
  "os": "linux",
  "os_version": "Ubuntu 22.04",
  "arch": "amd64",
  "version": "0.1.0",
  "instance_id": "b3f6c1a2-..."
}

{
  "collector_id": "col_...",
  "customer_id": "cus_...",
  "site_id": "site_...",
  "partner_id": "prt_...",
  "api_base_url": "https://api.assuriq.io",
  "auth_token": "at_...",
  "auth_token_expires_at": "2026-09-24T00:00:00Z",
  "client_cert_pem": null,
  "client_key_pem": null,
  "credential_note": "bearer-token; mTLS device certificates are planned",
  "heartbeat_interval_s": 60,
  "clock_skew_tolerance_ms": 5000,
  "modules": ["core-heartbeat", "port-discovery"],
  "scan_scopes": [
    {
      "cidrs": ["10.20.0.0/24"],
      "excludes": ["10.20.0.1"],
      "blocked_targets": [],
      "max_concurrency": 20,
      "discovery_only": true,
      "credentialed": false,
      "method": "tcp_connect"
    }
  ]
}

Heartbeat

Sent on the interval returned at enrollment (heartbeat_interval_s). All fields except the bearer token are optional; the server updates health, version, hostname, OS and arch, and last_seen from whatever is supplied.

{
  "collector_id": "col_...",
  "instance_id": "b3f6c1a2-...",
  "hostname": "web-scanner-01",
  "os": "linux",
  "os_version": "Ubuntu 22.04",
  "arch": "amd64",
  "version": "0.1.0",
  "status": "healthy",
  "sent_at": "2026-08-24T00:00:00Z",
  "cpu_pct": 4.2,
  "memory_pct": 18.5,
  "disk_free_pct": 71.0,
  "uptime_s": 86400,
  "queue_depth": 0,
  "active_job_id": null,
  "last_error": null
}

{
  "ok": true,
  "collector_id": "col_...",
  "customer_id": "cus_...",
  "site_id": "site_...",
  "state": "healthy",
  "server_time": "2026-08-24T00:00:01Z",
  "clock_skew_ms": 120,
  "heartbeat_interval_s": 60,
  "update": null,
  "commands": [],
  "scan_scopes": []
}

Observations

Uploads a batch of discovered hosts and their open ports. batch_id is an idempotency key: resubmitting the same batch_id after a network retry is safe and returns the original result rather than duplicating data.

{
  "batch_id": "b_2f1c...",
  "observed_at": "2026-08-24T00:05:00Z",
  "scan_job_id": "job_...",
  "collector_id": "col_...",
  "scope_cidrs": ["10.20.0.0/24"],
  "hosts": [
    {
      "ip": "10.20.0.42",
      "hostname": "printer-3f",
      "mac": "AA:BB:CC:00:11:22",
      "rtt_ms": 4,
      "observed_at": "2026-08-24T00:05:00Z",
      "open_ports": [
        { "port": 9100, "proto": "tcp", "service": "jetdirect", "state": "open" }
      ],
      "attributes": {}
    }
  ]
}

{
  "ok": true,
  "batch_id": "b_2f1c...",
  "accepted": 1,
  "rejected": 0,
  "created_assets": 1,
  "updated_assets": 0,
  "errors": [],
  "duplicate": false
}

Assets are reconciled in order of confidence: MAC address first, then hostname plus site, then IP address — so the same physical host is not duplicated across successive scans as its IP changes.

Topology fields (Collector 0.2.0-dev)

Collectors 0.2.0-dev and later may include optional per-host topology arrays alongside ip/hostname/open_ports. All fields are optional and 0.1.x payloads remain valid. AssurIQ stores the raw arrays as observations first, then derives interfaces, VLANs, addresses, routes, neighbors and forwarding entries, and finally computes graph edges labelled verified (LLDP/CDP neighbor) or inferred (forwarding table, route, subnet).

The response adds a topology summary: assets_with_topology, edges, subnets and links. Neighbors whose remote chassis cannot be matched to a known asset at the same site are kept as unresolved nodes rather than guessed.

Tenant and site binding rules

Every observations call is validated against the calling collector's assigned tenant and site before anything is written.

Error codes

• AIQ-ENR-005Enrollment token binding mismatch
  The token is valid but does not match the partner, customer or site the install attempted to enroll into.
• AIQ-ENR-006Customer missing
  The token's bound customer no longer exists, so enrollment cannot be completed.
• AIQ-ENR-007Site missing or belongs to a different customer
  The token's bound site no longer exists, or now belongs to a different customer than the token was issued for.
• AIQ-ENR-008Credential issuance failed
  Enrollment validated but the server could not issue a collector credential.
• AIQ-COL-008Collector ID mismatch
  A heartbeat or observations call included a collector_id that does not match the authenticated collector's own id.
• AIQ-COL-009Customer ID mismatch
  A request included a customer_id that does not match the authenticated collector's assigned customer.
• AIQ-COL-010Collector has no assigned site
  Observations were submitted by a collector that has not been assigned to a site.
• AIQ-COL-011Site ID mismatch
  A request included a site_id that does not match the authenticated collector's assigned site.
• AIQ-COL-012Assigned site invalid
  The collector's assigned site no longer exists or is otherwise invalid, so observations cannot be reconciled.
• AIQ-ING-002Observation processing failed
  The control plane accepted an observations batch but failed while reconciling it into assets.

Production hardening: the CSR flow

Related reading

• What the v0.1 collector does today
  A plain list of what the native v0.1 collector supports right now versus what is designed but not yet active, and what the DEV build badge means.
• Enrollment failures
  Symptom-first guide for AIQ-ENR-001 through AIQ-ENR-004: token, expiry, revocation and connectivity failures during enrollment.
• Discovery scope and safety
  CIDRs, exclusions, blocked targets, concurrency and maintenance windows: how scan scope is defined and enforced server-side.
• Collector health states explained
  Healthy, Degraded, Offline, Enrollment Pending, Update Required and Revoked — what each state means and what to check.