API reference — /api/av/*

POST /api/av/claim

Auth: X-Zeq-SM-Key: zsm_<…> (scope ≥ write). Body:

{
  "claim_type": "process_spawn",
  "claim_payload": {
    "instances_in_30_pulses": 42,
    "max_instances": 100,
    "exec_path": "/usr/bin/curl"
  },
  "device_id": "dev_abc123",
  "captured_at_zeqond": 2287568432,
  "hf_scores": [          // optional — agent-side HF computations
    { "hf_id": "HF8",  "value": 0.42 },
    { "hf_id": "HF15", "value": 0.91 }
  ]
}

Response 201:

{
  "ok": true,
  "audit_row_id": "uuid",
  "zeqond": 2287568432,
  "s_forensic": 0.412,
  "fired": false,
  "blockers": ["composite_below_theta"],
  "notified": [],
  "fingerprint": "5b8f2ca8..."
}

GET /api/av/devices?slug=<machine>

Auth: zeq_auth_token cookie (must be the machine owner). Response 200:

{
  "ok": true,
  "slug": "zeq07792026349",
  "devices": [
    {
      "device_id": "dev_abc123",
      "name": "laptop-zeq-01",
      "os": "linux",
      "installed_zeqond": "2287568432",
      "transition_id": "uuid"
    }
  ]
}

POST /api/av/devices

Auth: zeq_auth_token cookie (machine owner). Body:

{ "slug": "zeq07792026349", "name": "laptop-zeq-01", "os": "linux" }

Response 201:

{ "ok": true, "device_id": "dev_abc123", "transition_id": "uuid" }

GET /api/av/threats?slug=<machine>&window=24h

Auth: optionalAuth. Owner reads everything; non-owners on a private machine get 403. Public machines are readable by anyone.

window accepts <n>s|m|h|d. Default 24h.

Response 200:

{
  "ok": true,
  "slug": "zeq07792026349",
  "window": "24h",
  "count": 3,
  "threats": [
    {
      "transition_id": "uuid",
      "zeqond": "2287568432",
      "claim_type": "process_spawn",
      "device_id": "dev_abc123",
      "fingerprint": "5b8f2ca8...",
      "s_forensic": 0.91,
      "fired": true
    }
  ]
}

GET /api/av/mesh-feed?slug=<machine>

Auth: optionalAuth (same gate as /threats). Response 200:

{
  "ok": true,
  "slug": "zeq07792026349",
  "subscriptions": [
    {
      "publisher_slug": "prod-api-04",
      "tag": "av.threat.detected",
      "fire_count": 14,
      "last_fired_zeqond": "2287568430"
    }
  ]
}

Errors

HTTP	code	meaning
400	invalid_request	malformed body or missing required field
401	missing_api_key / invalid_api_key / unauthorized	auth failed
403	insufficient_scope / forbidden	authed but lacks permission
404	machine_not_found	slug doesn't map to a state machine
500	audit_write_failed	DB transaction failed; agent should retry