{"openapi":"3.1.0","info":{"title":"Physical & IoT Security API","version":"1.0.0","description":"Detect sensor anomalies, unusual door-access and tailgating signals, perimeter-breach and camera-tampering indicators, correlate multi-sensor alarms, analyze IoT device behaviour, and build building-security timelines—using caller-supplied event logs and telemetry with local temporal rules only. Paid with x402 exact USDC on Base. No account is required.","contact":{"email":"support@brainiac.software"},"x-guidance":"BRAINIAC.software is a pay-per-call API for software agents. No account or API key is required.\nPayment uses the x402 protocol with exact USDC on Base (chain id 8453). Each POST operation has a fixed USD price.\nHow to call an operation:\n1. POST a JSON body matching the operation's requestBody schema to the operation path. Include an Idempotency-Key header (64 hex characters, 32 random bytes).\n2. If you have not paid, the server responds 402 with payment requirements in the body. Pay the exact amount to the payTo address on Base.\n3. Retry the identical request with the same Idempotency-Key and add a payment-signature header containing the x402 payment payload. On success (200) the operation result is returned.\n4. Reuse the same Idempotency-Key only for retries of the same operation and request body; it will not be charged twice.\nAll outputs are compliance prechecks, drafts, or data lookups for human review. They are not official determinations, legal advice, identity confirmation, or certified filings. Verify time-sensitive or official data with the cited source before acting."},"servers":[{"url":"https://www.brainiac.software"}],"paths":{"/api/v1/physical-security/sensor-event-anomaly-detect":{"post":{"operationId":"detect_sensor_event_anomalies","summary":"Detect sensor-event anomalies","description":"Detect anomalies in caller-supplied sensor telemetry using thresholds, baselines, and local standard-deviation rules. Anomalies are not confirmed physical incidents.","tags":["physical-security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false},"files":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false}},"events":{"maxItems":20000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"eventType":{"type":"string","maxLength":120},"category":{"type":"string","enum":["sensor","door","perimeter","camera","alarm","iot","access","other"]},"deviceId":{"type":"string","maxLength":120},"deviceType":{"type":"string","maxLength":80},"zone":{"type":"string","maxLength":120},"building":{"type":"string","maxLength":120},"doorId":{"type":"string","maxLength":120},"cameraId":{"type":"string","maxLength":120},"userId":{"type":"string","maxLength":120},"badgeId":{"type":"string","maxLength":120},"direction":{"type":"string","enum":["in","out","unknown"]},"outcome":{"type":"string","enum":["granted","denied","forced","held","alarm","clear","unknown"]},"value":{"type":"number","minimum":-1000000000,"maximum":1000000000},"unit":{"type":"string","maxLength":40},"baseline":{"type":"number","minimum":-1000000000,"maximum":1000000000},"threshold":{"type":"number","minimum":-1000000000,"maximum":1000000000},"severity":{"type":"string","maxLength":40},"message":{"type":"string","maxLength":4000},"labels":{"maxItems":40,"type":"array","items":{"type":"string","maxLength":80}},"relatedEventIds":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":80}},"source":{"type":"string","maxLength":200}},"additionalProperties":false}},"asOf":{"type":"string","maxLength":40},"anomalyStdev":{"type":"number","minimum":1,"maximum":10},"doorWindowMinutes":{"type":"number","minimum":1,"maximum":10080},"tailgateSeconds":{"type":"number","minimum":1,"maximum":600},"correlationWindowMinutes":{"type":"number","minimum":1,"maximum":1440},"offlineMinutes":{"type":"number","minimum":1,"maximum":10080}},"additionalProperties":false},"example":{"asOf":"2026-11-04T21:00:00.000Z","anomalyStdev":3,"events":[{"id":"S1","at":"2026-11-04T20:00:00.000Z","category":"sensor","deviceId":"temp-1","eventType":"temperature","value":21,"baseline":21,"unit":"C","source":"Caller-supplied"},{"id":"S2","at":"2026-11-04T20:05:00.000Z","category":"sensor","deviceId":"temp-1","eventType":"temperature","value":22,"baseline":21,"unit":"C","source":"Caller-supplied"},{"id":"S3","at":"2026-11-04T20:10:00.000Z","category":"sensor","deviceId":"temp-1","eventType":"temperature","value":21.5,"baseline":21,"unit":"C","source":"Caller-supplied"},{"id":"S4","at":"2026-11-04T20:15:00.000Z","category":"sensor","deviceId":"temp-1","eventType":"temperature","value":48,"baseline":21,"threshold":30,"unit":"C","labels":["anomaly"],"source":"Caller-supplied"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"itemCount":{"type":"number"},"anomalyStdev":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"detector":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"observedFacts":{"type":"array","items":{"type":"string"}},"inferredThreat":{"type":"string"},"confidence":{"type":"string"},"relatedEventIds":{"type":"array","items":{"type":"string"}},"firstAt":{"type":"string"},"lastAt":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string"},"at":{"type":"string"},"fact":{"type":"string"},"inference":{"type":"string"},"confidence":{"type":"string"}},"additionalProperties":true}},"source":{"type":"string"},"confirmedIncident":{"type":"boolean"}},"additionalProperties":true}},"paidProviderUsed":{"type":"boolean"},"apiKeyRequired":{"type":"boolean"},"physicalSystemConnected":{"type":"boolean"},"deviceControlled":{"type":"boolean"},"networkAccessed":{"type":"boolean"},"confirmedIncidentClaimed":{"type":"boolean"},"findings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"code":{"type":"string"},"subject":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T21:00:00.000Z","status":"detected","itemCount":1,"anomalyStdev":3,"items":[{"id":"sensor-anomaly-temp_1","detector":"sensor-event-anomaly-detect","title":"Sensor telemetry anomaly","status":"signal","observedFacts":["Device temp_1 value 48 met/exceeded threshold 30.","Value 48 deviates ≥50% from baseline 21.","Event S4 carries anomaly/fault wording or labels."],"inferredThreat":"Unusual sensor values may indicate equipment fault, environmental change, or security-relevant disturbance.","confidence":"medium","relatedEventIds":["S4"],"firstAt":"2026-11-04T20:15:00.000Z","lastAt":"2026-11-04T20:15:00.000Z","reasons":["threshold_exceeded","baseline_deviation","explicit_anomaly_label"],"evidence":[{"eventId":"S4","at":"2026-11-04T20:15:00.000Z","fact":"temperature; device=temp-1; value=48C","inference":"Sensor anomaly is a telemetry indicator, not a confirmed physical incident.","confidence":"medium"}],"source":"Caller-supplied sensor telemetry; local anomaly rules","confirmedIncident":false}],"paidProviderUsed":false,"apiKeyRequired":false,"physicalSystemConnected":false,"deviceControlled":false,"networkAccessed":false,"confirmedIncidentClaimed":false,"findings":[{"kind":"conflict","code":"sensor_anomaly","subject":"temp_1","detail":"Sensor anomalies: threshold_exceeded, baseline_deviation, explicit_anomaly_label (confirmedIncident=false)."}],"limitations":["Physical/IoT event logs and telemetry are copied only from caller-supplied fields. Physical security systems are not contacted and devices are never controlled.","Temporal correlation and anomaly rules run locally over supplied records. Missing values are not invented.","Observed facts are separated from inferred threat hypotheses. Anomalies are not labeled confirmed physical incidents without sufficient multi-signal evidence.","Configurable windows/thresholds apply only when supplied; otherwise documented defaults are used.","No paid physical-security feed is used and no API key is required."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{}}]}}},"/api/v1/physical-security/door-access-pattern-detect":{"post":{"operationId":"detect_unusual_door_access_patterns","summary":"Detect unusual door-access patterns","description":"Identify unusual access patterns from caller-supplied door-entry logs (denials, forced doors, held-open, after-hours). Not a confirmed intrusion.","tags":["physical-security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false},"files":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false}},"events":{"maxItems":20000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"eventType":{"type":"string","maxLength":120},"category":{"type":"string","enum":["sensor","door","perimeter","camera","alarm","iot","access","other"]},"deviceId":{"type":"string","maxLength":120},"deviceType":{"type":"string","maxLength":80},"zone":{"type":"string","maxLength":120},"building":{"type":"string","maxLength":120},"doorId":{"type":"string","maxLength":120},"cameraId":{"type":"string","maxLength":120},"userId":{"type":"string","maxLength":120},"badgeId":{"type":"string","maxLength":120},"direction":{"type":"string","enum":["in","out","unknown"]},"outcome":{"type":"string","enum":["granted","denied","forced","held","alarm","clear","unknown"]},"value":{"type":"number","minimum":-1000000000,"maximum":1000000000},"unit":{"type":"string","maxLength":40},"baseline":{"type":"number","minimum":-1000000000,"maximum":1000000000},"threshold":{"type":"number","minimum":-1000000000,"maximum":1000000000},"severity":{"type":"string","maxLength":40},"message":{"type":"string","maxLength":4000},"labels":{"maxItems":40,"type":"array","items":{"type":"string","maxLength":80}},"relatedEventIds":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":80}},"source":{"type":"string","maxLength":200}},"additionalProperties":false}},"asOf":{"type":"string","maxLength":40},"anomalyStdev":{"type":"number","minimum":1,"maximum":10},"doorWindowMinutes":{"type":"number","minimum":1,"maximum":10080},"tailgateSeconds":{"type":"number","minimum":1,"maximum":600},"correlationWindowMinutes":{"type":"number","minimum":1,"maximum":1440},"offlineMinutes":{"type":"number","minimum":1,"maximum":10080}},"additionalProperties":false},"example":{"asOf":"2026-11-04T21:00:00.000Z","doorWindowMinutes":60,"events":[{"id":"D1","at":"2026-11-04T20:00:00.000Z","category":"door","doorId":"door-a","eventType":"access","outcome":"denied","badgeId":"B1","source":"Caller-supplied"},{"id":"D2","at":"2026-11-04T20:01:00.000Z","category":"door","doorId":"door-a","eventType":"access","outcome":"denied","badgeId":"B1","source":"Caller-supplied"},{"id":"D3","at":"2026-11-04T20:02:00.000Z","category":"door","doorId":"door-a","eventType":"access","outcome":"denied","badgeId":"B2","source":"Caller-supplied"},{"id":"D4","at":"2026-11-04T20:03:00.000Z","category":"door","doorId":"door-a","eventType":"forced_open","outcome":"forced","source":"Caller-supplied"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"itemCount":{"type":"number"},"windowMinutes":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"detector":{"type":"string"},"title":{"type":"string"},"observedFacts":{"type":"array","items":{"type":"string"}},"inferredThreat":{"type":"string"},"confidence":{"type":"string"},"relatedEventIds":{"type":"array","items":{"type":"string"}},"firstAt":{"type":"string"},"lastAt":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string"},"at":{"type":"string"},"fact":{"type":"string"},"inference":{"type":"string"},"confidence":{"type":"string"}},"additionalProperties":true}},"source":{"type":"string"},"status":{"type":"string"},"confirmedIncident":{"type":"boolean"}},"additionalProperties":true}},"paidProviderUsed":{"type":"boolean"},"apiKeyRequired":{"type":"boolean"},"physicalSystemConnected":{"type":"boolean"},"deviceControlled":{"type":"boolean"},"networkAccessed":{"type":"boolean"},"confirmedIncidentClaimed":{"type":"boolean"},"findings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"code":{"type":"string"},"subject":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T21:00:00.000Z","status":"detected","itemCount":1,"windowMinutes":60,"items":[{"id":"door-pattern-door_a-D1","detector":"door-access-pattern-detect","title":"Unusual door-access pattern","observedFacts":["3 denied access attempts within 60 minutes.","1 forced-door indicator(s)."],"inferredThreat":"Unusual door activity can indicate unauthorized access attempts or propped doors.","confidence":"high","relatedEventIds":["D1","D2","D3","D4"],"firstAt":"2026-11-04T20:00:00.000Z","lastAt":"2026-11-04T20:03:00.000Z","reasons":["repeated_denials","forced_door"],"evidence":[{"eventId":"D1","at":"2026-11-04T20:00:00.000Z","fact":"access; door=door-a; outcome=denied","inference":"Door-pattern indicator only; not a confirmed physical incident.","confidence":"medium"},{"eventId":"D2","at":"2026-11-04T20:01:00.000Z","fact":"access; door=door-a; outcome=denied","inference":"Door-pattern indicator only; not a confirmed physical incident.","confidence":"medium"},{"eventId":"D3","at":"2026-11-04T20:02:00.000Z","fact":"access; door=door-a; outcome=denied","inference":"Door-pattern indicator only; not a confirmed physical incident.","confidence":"medium"},{"eventId":"D4","at":"2026-11-04T20:03:00.000Z","fact":"forced_open; door=door-a; outcome=forced","inference":"Door-pattern indicator only; not a confirmed physical incident.","confidence":"medium"}],"source":"Caller-supplied door/access logs; local rules","status":"signal","confirmedIncident":false}],"paidProviderUsed":false,"apiKeyRequired":false,"physicalSystemConnected":false,"deviceControlled":false,"networkAccessed":false,"confirmedIncidentClaimed":false,"findings":[{"kind":"conflict","code":"door_access_pattern","subject":"door_a","detail":"Door-access indicators: repeated_denials, forced_door (confirmedIncident=false)."}],"limitations":["Physical/IoT event logs and telemetry are copied only from caller-supplied fields. Physical security systems are not contacted and devices are never controlled.","Temporal correlation and anomaly rules run locally over supplied records. Missing values are not invented.","Observed facts are separated from inferred threat hypotheses. Anomalies are not labeled confirmed physical incidents without sufficient multi-signal evidence.","Configurable windows/thresholds apply only when supplied; otherwise documented defaults are used.","No paid physical-security feed is used and no API key is required."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{}}]}}},"/api/v1/physical-security/access-tailgating-signal-detect":{"post":{"operationId":"detect_tailgating_signals","summary":"Detect tailgating signals","description":"Identify possible tailgating using caller-supplied access grants correlated with nearby motion/occupancy or unbadged second passages. Not visually confirmed.","tags":["physical-security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false},"files":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false}},"events":{"maxItems":20000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"eventType":{"type":"string","maxLength":120},"category":{"type":"string","enum":["sensor","door","perimeter","camera","alarm","iot","access","other"]},"deviceId":{"type":"string","maxLength":120},"deviceType":{"type":"string","maxLength":80},"zone":{"type":"string","maxLength":120},"building":{"type":"string","maxLength":120},"doorId":{"type":"string","maxLength":120},"cameraId":{"type":"string","maxLength":120},"userId":{"type":"string","maxLength":120},"badgeId":{"type":"string","maxLength":120},"direction":{"type":"string","enum":["in","out","unknown"]},"outcome":{"type":"string","enum":["granted","denied","forced","held","alarm","clear","unknown"]},"value":{"type":"number","minimum":-1000000000,"maximum":1000000000},"unit":{"type":"string","maxLength":40},"baseline":{"type":"number","minimum":-1000000000,"maximum":1000000000},"threshold":{"type":"number","minimum":-1000000000,"maximum":1000000000},"severity":{"type":"string","maxLength":40},"message":{"type":"string","maxLength":4000},"labels":{"maxItems":40,"type":"array","items":{"type":"string","maxLength":80}},"relatedEventIds":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":80}},"source":{"type":"string","maxLength":200}},"additionalProperties":false}},"asOf":{"type":"string","maxLength":40},"anomalyStdev":{"type":"number","minimum":1,"maximum":10},"doorWindowMinutes":{"type":"number","minimum":1,"maximum":10080},"tailgateSeconds":{"type":"number","minimum":1,"maximum":600},"correlationWindowMinutes":{"type":"number","minimum":1,"maximum":1440},"offlineMinutes":{"type":"number","minimum":1,"maximum":10080}},"additionalProperties":false},"example":{"asOf":"2026-11-04T21:00:00.000Z","tailgateSeconds":8,"events":[{"id":"A1","at":"2026-11-04T20:00:00.000Z","category":"door","doorId":"lobby","zone":"lobby","eventType":"access","outcome":"granted","badgeId":"B9","direction":"in","source":"Caller-supplied"},{"id":"A2","at":"2026-11-04T20:00:04.000Z","category":"door","doorId":"lobby","zone":"lobby","eventType":"passage","outcome":"unknown","source":"Caller-supplied"},{"id":"M1","at":"2026-11-04T20:00:05.000Z","category":"sensor","deviceId":"pir-lobby","zone":"lobby","eventType":"motion","value":2,"unit":"people","labels":["motion"],"source":"Caller-supplied"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"itemCount":{"type":"number"},"tailgateSeconds":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"detector":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"observedFacts":{"type":"array","items":{"type":"string"}},"inferredThreat":{"type":"string"},"confidence":{"type":"string"},"relatedEventIds":{"type":"array","items":{"type":"string"}},"firstAt":{"type":"string"},"lastAt":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string"},"at":{"type":"string"},"fact":{"type":"string"},"inference":{"type":"string"},"confidence":{"type":"string"}},"additionalProperties":true}},"source":{"type":"string"},"confirmedIncident":{"type":"boolean"}},"additionalProperties":true}},"paidProviderUsed":{"type":"boolean"},"apiKeyRequired":{"type":"boolean"},"physicalSystemConnected":{"type":"boolean"},"deviceControlled":{"type":"boolean"},"networkAccessed":{"type":"boolean"},"confirmedIncidentClaimed":{"type":"boolean"},"findings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"code":{"type":"string"},"subject":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T21:00:00.000Z","status":"detected","itemCount":1,"tailgateSeconds":8,"items":[{"id":"tailgate-lobby-A1","detector":"access-tailgating-signal-detect","title":"Possible tailgating signal","status":"signal","observedFacts":["Second door passage within 8s without badge/user id.","1 motion/occupancy event(s) near a single badge grant.","Occupancy/people-count ≥2 near a single grant."],"inferredThreat":"Access plus nearby motion/second passage may indicate tailgating.","confidence":"medium","relatedEventIds":["A1","A2","M1"],"firstAt":"2026-11-04T20:00:00.000Z","lastAt":"2026-11-04T20:00:05.000Z","reasons":["ungated_second_passage","motion_after_single_badge","people_count_gt_badges"],"evidence":[{"eventId":"A1","at":"2026-11-04T20:00:00.000Z","fact":"access; door=lobby; zone=lobby; outcome=granted","inference":"Tailgating is inferred from timing correlation, not visually confirmed.","confidence":"medium"},{"eventId":"A2","at":"2026-11-04T20:00:04.000Z","fact":"passage; door=lobby; zone=lobby","inference":"Tailgating is inferred from timing correlation, not visually confirmed.","confidence":"medium"},{"eventId":"M1","at":"2026-11-04T20:00:05.000Z","fact":"motion; device=pir-lobby; zone=lobby; value=2people","inference":"Tailgating is inferred from timing correlation, not visually confirmed.","confidence":"medium"}],"source":"Caller-supplied access/sensor events; local timing rules","confirmedIncident":false}],"paidProviderUsed":false,"apiKeyRequired":false,"physicalSystemConnected":false,"deviceControlled":false,"networkAccessed":false,"confirmedIncidentClaimed":false,"findings":[{"kind":"conflict","code":"tailgating","subject":"lobby","detail":"Tailgating indicators: ungated_second_passage, motion_after_single_badge, people_count_gt_badges (confirmedIncident=false)."}],"limitations":["Physical/IoT event logs and telemetry are copied only from caller-supplied fields. Physical security systems are not contacted and devices are never controlled.","Temporal correlation and anomaly rules run locally over supplied records. Missing values are not invented.","Observed facts are separated from inferred threat hypotheses. Anomalies are not labeled confirmed physical incidents without sufficient multi-signal evidence.","Configurable windows/thresholds apply only when supplied; otherwise documented defaults are used.","No paid physical-security feed is used and no API key is required."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}}]}}},"/api/v1/physical-security/perimeter-breach-signal-detect":{"post":{"operationId":"detect_perimeter_breach_signals","summary":"Detect perimeter-breach signals","description":"Analyze caller-supplied perimeter sensor events for possible breaches. Multi-sensor alarms raise confidence; still not a confirmed physical breach.","tags":["physical-security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false},"files":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false}},"events":{"maxItems":20000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"eventType":{"type":"string","maxLength":120},"category":{"type":"string","enum":["sensor","door","perimeter","camera","alarm","iot","access","other"]},"deviceId":{"type":"string","maxLength":120},"deviceType":{"type":"string","maxLength":80},"zone":{"type":"string","maxLength":120},"building":{"type":"string","maxLength":120},"doorId":{"type":"string","maxLength":120},"cameraId":{"type":"string","maxLength":120},"userId":{"type":"string","maxLength":120},"badgeId":{"type":"string","maxLength":120},"direction":{"type":"string","enum":["in","out","unknown"]},"outcome":{"type":"string","enum":["granted","denied","forced","held","alarm","clear","unknown"]},"value":{"type":"number","minimum":-1000000000,"maximum":1000000000},"unit":{"type":"string","maxLength":40},"baseline":{"type":"number","minimum":-1000000000,"maximum":1000000000},"threshold":{"type":"number","minimum":-1000000000,"maximum":1000000000},"severity":{"type":"string","maxLength":40},"message":{"type":"string","maxLength":4000},"labels":{"maxItems":40,"type":"array","items":{"type":"string","maxLength":80}},"relatedEventIds":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":80}},"source":{"type":"string","maxLength":200}},"additionalProperties":false}},"asOf":{"type":"string","maxLength":40},"anomalyStdev":{"type":"number","minimum":1,"maximum":10},"doorWindowMinutes":{"type":"number","minimum":1,"maximum":10080},"tailgateSeconds":{"type":"number","minimum":1,"maximum":600},"correlationWindowMinutes":{"type":"number","minimum":1,"maximum":1440},"offlineMinutes":{"type":"number","minimum":1,"maximum":10080}},"additionalProperties":false},"example":{"asOf":"2026-11-04T21:00:00.000Z","events":[{"id":"P1","at":"2026-11-04T20:10:00.000Z","category":"perimeter","zone":"north-fence","deviceId":"beam-1","eventType":"intrusion_alarm","outcome":"alarm","severity":"high","message":"beam trip","source":"Caller-supplied"},{"id":"P2","at":"2026-11-04T20:10:20.000Z","category":"perimeter","zone":"north-fence","deviceId":"pir-2","eventType":"intrusion_alarm","outcome":"alarm","severity":"high","message":"climb suspected","labels":["breach"],"source":"Caller-supplied"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"itemCount":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"detector":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"observedFacts":{"type":"array","items":{"type":"string"}},"inferredThreat":{"type":"string"},"confidence":{"type":"string"},"relatedEventIds":{"type":"array","items":{"type":"string"}},"firstAt":{"type":"string"},"lastAt":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string"},"at":{"type":"string"},"fact":{"type":"string"},"inference":{"type":"string"},"confidence":{"type":"string"}},"additionalProperties":true}},"source":{"type":"string"},"confirmedIncident":{"type":"boolean"}},"additionalProperties":true}},"paidProviderUsed":{"type":"boolean"},"apiKeyRequired":{"type":"boolean"},"physicalSystemConnected":{"type":"boolean"},"deviceControlled":{"type":"boolean"},"networkAccessed":{"type":"boolean"},"confirmedIncidentClaimed":{"type":"boolean"},"findings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"code":{"type":"string"},"subject":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T21:00:00.000Z","status":"detected","itemCount":1,"items":[{"id":"perimeter-north_fence-P1","detector":"perimeter-breach-signal-detect","title":"Possible perimeter breach signal","status":"signal","observedFacts":["2 perimeter alarm/breach-style event(s).","2 devices alarmed in zone north_fence.","Event message/labels include breach/cut/climb/tamper wording."],"inferredThreat":"Perimeter sensor alarms may indicate intrusion attempts; not a confirmed breach by themselves.","confidence":"medium","relatedEventIds":["P1","P2"],"firstAt":"2026-11-04T20:10:00.000Z","lastAt":"2026-11-04T20:10:20.000Z","reasons":["perimeter_alarm","multi_sensor_zone","breach_wording"],"evidence":[{"eventId":"P1","at":"2026-11-04T20:10:00.000Z","fact":"intrusion_alarm; device=beam-1; zone=north-fence; outcome=alarm; msg=beam trip","inference":"Perimeter signal only; physical confirmation not performed.","confidence":"medium"},{"eventId":"P2","at":"2026-11-04T20:10:20.000Z","fact":"intrusion_alarm; device=pir-2; zone=north-fence; outcome=alarm; msg=climb suspected","inference":"Perimeter signal only; physical confirmation not performed.","confidence":"medium"}],"source":"Caller-supplied perimeter events; local correlation","confirmedIncident":false}],"paidProviderUsed":false,"apiKeyRequired":false,"physicalSystemConnected":false,"deviceControlled":false,"networkAccessed":false,"confirmedIncidentClaimed":false,"findings":[{"kind":"conflict","code":"perimeter_breach","subject":"north_fence","detail":"Perimeter indicators: perimeter_alarm, multi_sensor_zone, breach_wording (confirmedIncident=false)."}],"limitations":["Physical/IoT event logs and telemetry are copied only from caller-supplied fields. Physical security systems are not contacted and devices are never controlled.","Temporal correlation and anomaly rules run locally over supplied records. Missing values are not invented.","Observed facts are separated from inferred threat hypotheses. Anomalies are not labeled confirmed physical incidents without sufficient multi-signal evidence.","Configurable windows/thresholds apply only when supplied; otherwise documented defaults are used.","No paid physical-security feed is used and no API key is required."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{}}]}}},"/api/v1/physical-security/camera-tampering-signal-detect":{"post":{"operationId":"detect_camera_tampering_signals","summary":"Detect camera-tampering signals","description":"Identify camera tampering indicators from caller-supplied telemetry (covered/moved/signal-loss). Scene content is not visually verified.","tags":["physical-security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false},"files":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false}},"events":{"maxItems":20000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"eventType":{"type":"string","maxLength":120},"category":{"type":"string","enum":["sensor","door","perimeter","camera","alarm","iot","access","other"]},"deviceId":{"type":"string","maxLength":120},"deviceType":{"type":"string","maxLength":80},"zone":{"type":"string","maxLength":120},"building":{"type":"string","maxLength":120},"doorId":{"type":"string","maxLength":120},"cameraId":{"type":"string","maxLength":120},"userId":{"type":"string","maxLength":120},"badgeId":{"type":"string","maxLength":120},"direction":{"type":"string","enum":["in","out","unknown"]},"outcome":{"type":"string","enum":["granted","denied","forced","held","alarm","clear","unknown"]},"value":{"type":"number","minimum":-1000000000,"maximum":1000000000},"unit":{"type":"string","maxLength":40},"baseline":{"type":"number","minimum":-1000000000,"maximum":1000000000},"threshold":{"type":"number","minimum":-1000000000,"maximum":1000000000},"severity":{"type":"string","maxLength":40},"message":{"type":"string","maxLength":4000},"labels":{"maxItems":40,"type":"array","items":{"type":"string","maxLength":80}},"relatedEventIds":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":80}},"source":{"type":"string","maxLength":200}},"additionalProperties":false}},"asOf":{"type":"string","maxLength":40},"anomalyStdev":{"type":"number","minimum":1,"maximum":10},"doorWindowMinutes":{"type":"number","minimum":1,"maximum":10080},"tailgateSeconds":{"type":"number","minimum":1,"maximum":600},"correlationWindowMinutes":{"type":"number","minimum":1,"maximum":1440},"offlineMinutes":{"type":"number","minimum":1,"maximum":10080}},"additionalProperties":false},"example":{"asOf":"2026-11-04T21:00:00.000Z","events":[{"id":"C1","at":"2026-11-04T19:55:00.000Z","category":"camera","cameraId":"cam-12","eventType":"video_loss","outcome":"alarm","message":"signal loss","source":"Caller-supplied"},{"id":"C2","at":"2026-11-04T19:56:00.000Z","category":"camera","cameraId":"cam-12","eventType":"tamper","message":"lens covered","value":2,"threshold":5,"unit":"luminance","source":"Caller-supplied"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"itemCount":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"detector":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"observedFacts":{"type":"array","items":{"type":"string"}},"inferredThreat":{"type":"string"},"confidence":{"type":"string"},"relatedEventIds":{"type":"array","items":{"type":"string"}},"firstAt":{"type":"string"},"lastAt":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string"},"at":{"type":"string"},"fact":{"type":"string"},"inference":{"type":"string"},"confidence":{"type":"string"}},"additionalProperties":true}},"source":{"type":"string"},"confirmedIncident":{"type":"boolean"}},"additionalProperties":true}},"paidProviderUsed":{"type":"boolean"},"apiKeyRequired":{"type":"boolean"},"physicalSystemConnected":{"type":"boolean"},"deviceControlled":{"type":"boolean"},"networkAccessed":{"type":"boolean"},"confirmedIncidentClaimed":{"type":"boolean"},"findings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"code":{"type":"string"},"subject":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T21:00:00.000Z","status":"detected","itemCount":1,"items":[{"id":"camera-tamper-cam_12","detector":"camera-tampering-signal-detect","title":"Camera tampering indicators","status":"signal","observedFacts":["Camera cam_12 event C1 indicates tamper/obstruction/signal loss.","Camera cam_12 event C2 indicates tamper/obstruction/signal loss."],"inferredThreat":"Camera telemetry anomalies can indicate tampering or obstruction.","confidence":"medium","relatedEventIds":["C1","C2"],"firstAt":"2026-11-04T19:55:00.000Z","lastAt":"2026-11-04T19:56:00.000Z","reasons":["tamper_indicator","camera_alarm"],"evidence":[{"eventId":"C1","at":"2026-11-04T19:55:00.000Z","fact":"video_loss; camera=cam-12; outcome=alarm; msg=signal loss","inference":"Tampering indicator from supplied telemetry only; scene not visually verified.","confidence":"medium"},{"eventId":"C2","at":"2026-11-04T19:56:00.000Z","fact":"tamper; camera=cam-12; value=2luminance; msg=lens covered","inference":"Tampering indicator from supplied telemetry only; scene not visually verified.","confidence":"medium"}],"source":"Caller-supplied camera telemetry; local rules","confirmedIncident":false}],"paidProviderUsed":false,"apiKeyRequired":false,"physicalSystemConnected":false,"deviceControlled":false,"networkAccessed":false,"confirmedIncidentClaimed":false,"findings":[{"kind":"conflict","code":"camera_tamper","subject":"cam_12","detail":"Camera-tamper indicators: tamper_indicator, camera_alarm (confirmedIncident=false)."}],"limitations":["Physical/IoT event logs and telemetry are copied only from caller-supplied fields. Physical security systems are not contacted and devices are never controlled.","Temporal correlation and anomaly rules run locally over supplied records. Missing values are not invented.","Observed facts are separated from inferred threat hypotheses. Anomalies are not labeled confirmed physical incidents without sufficient multi-signal evidence.","Configurable windows/thresholds apply only when supplied; otherwise documented defaults are used.","No paid physical-security feed is used and no API key is required."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{}}]}}},"/api/v1/physical-security/alarm-correlation-analyze":{"post":{"operationId":"correlate_multi_sensor_alarms","summary":"Correlate multi-sensor alarms","description":"Correlate alarms from multiple caller-supplied sensors into possible incident groups using time windows. Correlation is not confirmation of a physical incident.","tags":["physical-security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false},"files":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false}},"events":{"maxItems":20000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"eventType":{"type":"string","maxLength":120},"category":{"type":"string","enum":["sensor","door","perimeter","camera","alarm","iot","access","other"]},"deviceId":{"type":"string","maxLength":120},"deviceType":{"type":"string","maxLength":80},"zone":{"type":"string","maxLength":120},"building":{"type":"string","maxLength":120},"doorId":{"type":"string","maxLength":120},"cameraId":{"type":"string","maxLength":120},"userId":{"type":"string","maxLength":120},"badgeId":{"type":"string","maxLength":120},"direction":{"type":"string","enum":["in","out","unknown"]},"outcome":{"type":"string","enum":["granted","denied","forced","held","alarm","clear","unknown"]},"value":{"type":"number","minimum":-1000000000,"maximum":1000000000},"unit":{"type":"string","maxLength":40},"baseline":{"type":"number","minimum":-1000000000,"maximum":1000000000},"threshold":{"type":"number","minimum":-1000000000,"maximum":1000000000},"severity":{"type":"string","maxLength":40},"message":{"type":"string","maxLength":4000},"labels":{"maxItems":40,"type":"array","items":{"type":"string","maxLength":80}},"relatedEventIds":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":80}},"source":{"type":"string","maxLength":200}},"additionalProperties":false}},"asOf":{"type":"string","maxLength":40},"anomalyStdev":{"type":"number","minimum":1,"maximum":10},"doorWindowMinutes":{"type":"number","minimum":1,"maximum":10080},"tailgateSeconds":{"type":"number","minimum":1,"maximum":600},"correlationWindowMinutes":{"type":"number","minimum":1,"maximum":1440},"offlineMinutes":{"type":"number","minimum":1,"maximum":10080}},"additionalProperties":false},"example":{"asOf":"2026-11-04T21:00:00.000Z","correlationWindowMinutes":15,"events":[{"id":"A1","at":"2026-11-04T20:00:00.000Z","category":"alarm","deviceId":"panel-1","zone":"lobby","eventType":"intrusion_alarm","outcome":"alarm","severity":"high","source":"Caller-supplied"},{"id":"A2","at":"2026-11-04T20:01:00.000Z","category":"door","deviceId":"door-lobby","zone":"lobby","eventType":"forced_open","outcome":"forced","severity":"high","source":"Caller-supplied"},{"id":"A3","at":"2026-11-04T20:02:00.000Z","category":"camera","cameraId":"cam-lobby","eventType":"motion_alarm","outcome":"alarm","severity":"medium","source":"Caller-supplied"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"itemCount":{"type":"number"},"windowMinutes":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"detector":{"type":"string"},"title":{"type":"string"},"observedFacts":{"type":"array","items":{"type":"string"}},"inferredThreat":{"type":"string"},"confidence":{"type":"string"},"relatedEventIds":{"type":"array","items":{"type":"string"}},"firstAt":{"type":"string"},"lastAt":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string"},"at":{"type":"string"},"fact":{"type":"string"},"inference":{"type":"string"},"confidence":{"type":"string"}},"additionalProperties":true}},"source":{"type":"string"},"status":{"type":"string"},"confirmedIncident":{"type":"boolean"}},"additionalProperties":true}},"paidProviderUsed":{"type":"boolean"},"apiKeyRequired":{"type":"boolean"},"physicalSystemConnected":{"type":"boolean"},"deviceControlled":{"type":"boolean"},"networkAccessed":{"type":"boolean"},"confirmedIncidentClaimed":{"type":"boolean"},"findings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"code":{"type":"string"},"subject":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T21:00:00.000Z","status":"detected","itemCount":1,"windowMinutes":15,"items":[{"id":"alarm-corr-A1","detector":"alarm-correlation-analyze","title":"Correlated multi-sensor alarms","observedFacts":["3 alarm-severity events within 15 minutes.","Alarms across devices: panel-1, door-lobby, cam-lobby.","Categories involved: alarm, door, camera."],"inferredThreat":"Temporally clustered alarms may represent one incident spanning sensors.","confidence":"high","relatedEventIds":["A1","A2","A3"],"firstAt":"2026-11-04T20:00:00.000Z","lastAt":"2026-11-04T20:02:00.000Z","reasons":["multi_device_alarms","cross_category_alarms"],"evidence":[{"eventId":"A1","at":"2026-11-04T20:00:00.000Z","fact":"intrusion_alarm; device=panel-1; zone=lobby; outcome=alarm","inference":"Correlation groups alarms; does not confirm a physical incident.","confidence":"medium"},{"eventId":"A2","at":"2026-11-04T20:01:00.000Z","fact":"forced_open; device=door-lobby; zone=lobby; outcome=forced","inference":"Correlation groups alarms; does not confirm a physical incident.","confidence":"medium"},{"eventId":"A3","at":"2026-11-04T20:02:00.000Z","fact":"motion_alarm; camera=cam-lobby; outcome=alarm","inference":"Correlation groups alarms; does not confirm a physical incident.","confidence":"medium"}],"source":"Caller-supplied alarms; local time-window correlation","status":"signal","confirmedIncident":false}],"paidProviderUsed":false,"apiKeyRequired":false,"physicalSystemConnected":false,"deviceControlled":false,"networkAccessed":false,"confirmedIncidentClaimed":false,"findings":[{"kind":"conflict","code":"alarm_correlation","subject":"A1","detail":"Correlated alarms via multi_device_alarms, cross_category_alarms (confirmedIncident=false)."}],"limitations":["Physical/IoT event logs and telemetry are copied only from caller-supplied fields. Physical security systems are not contacted and devices are never controlled.","Temporal correlation and anomaly rules run locally over supplied records. Missing values are not invented.","Observed facts are separated from inferred threat hypotheses. Anomalies are not labeled confirmed physical incidents without sufficient multi-signal evidence.","Configurable windows/thresholds apply only when supplied; otherwise documented defaults are used.","No paid physical-security feed is used and no API key is required."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}}]}}},"/api/v1/physical-security/iot-device-behavior-analyze":{"post":{"operationId":"analyze_iot_device_behaviour","summary":"Analyze IoT device behaviour","description":"Identify unusual IoT device behaviour from caller-supplied telemetry (reporting gaps, outliers, unexpected reboot/config events). Devices are never contacted or controlled.","tags":["physical-security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false},"files":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false}},"events":{"maxItems":20000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"eventType":{"type":"string","maxLength":120},"category":{"type":"string","enum":["sensor","door","perimeter","camera","alarm","iot","access","other"]},"deviceId":{"type":"string","maxLength":120},"deviceType":{"type":"string","maxLength":80},"zone":{"type":"string","maxLength":120},"building":{"type":"string","maxLength":120},"doorId":{"type":"string","maxLength":120},"cameraId":{"type":"string","maxLength":120},"userId":{"type":"string","maxLength":120},"badgeId":{"type":"string","maxLength":120},"direction":{"type":"string","enum":["in","out","unknown"]},"outcome":{"type":"string","enum":["granted","denied","forced","held","alarm","clear","unknown"]},"value":{"type":"number","minimum":-1000000000,"maximum":1000000000},"unit":{"type":"string","maxLength":40},"baseline":{"type":"number","minimum":-1000000000,"maximum":1000000000},"threshold":{"type":"number","minimum":-1000000000,"maximum":1000000000},"severity":{"type":"string","maxLength":40},"message":{"type":"string","maxLength":4000},"labels":{"maxItems":40,"type":"array","items":{"type":"string","maxLength":80}},"relatedEventIds":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":80}},"source":{"type":"string","maxLength":200}},"additionalProperties":false}},"asOf":{"type":"string","maxLength":40},"anomalyStdev":{"type":"number","minimum":1,"maximum":10},"doorWindowMinutes":{"type":"number","minimum":1,"maximum":10080},"tailgateSeconds":{"type":"number","minimum":1,"maximum":600},"correlationWindowMinutes":{"type":"number","minimum":1,"maximum":1440},"offlineMinutes":{"type":"number","minimum":1,"maximum":10080}},"additionalProperties":false},"example":{"asOf":"2026-11-04T21:00:00.000Z","offlineMinutes":30,"events":[{"id":"I1","at":"2026-11-04T18:00:00.000Z","category":"iot","deviceId":"lock-7","deviceType":"lock","eventType":"heartbeat","value":1,"source":"Caller-supplied"},{"id":"I2","at":"2026-11-04T19:00:00.000Z","category":"iot","deviceId":"lock-7","deviceType":"lock","eventType":"heartbeat","value":1,"source":"Caller-supplied"},{"id":"I3","at":"2026-11-04T20:30:00.000Z","category":"iot","deviceId":"lock-7","deviceType":"lock","eventType":"reboot","message":"unexpected reboot","labels":["unexpected_behavior"],"source":"Caller-supplied"},{"id":"I4","at":"2026-11-04T20:31:00.000Z","category":"iot","deviceId":"lock-7","deviceType":"lock","eventType":"config_change","message":"unauthorized config change","source":"Caller-supplied"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"itemCount":{"type":"number"},"offlineMinutes":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"detector":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"observedFacts":{"type":"array","items":{"type":"string"}},"inferredThreat":{"type":"string"},"confidence":{"type":"string"},"relatedEventIds":{"type":"array","items":{"type":"string"}},"firstAt":{"type":"string"},"lastAt":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string"},"at":{"type":"string"},"fact":{"type":"string"},"inference":{"type":"string"},"confidence":{"type":"string"}},"additionalProperties":true}},"source":{"type":"string"},"confirmedIncident":{"type":"boolean"}},"additionalProperties":true}},"paidProviderUsed":{"type":"boolean"},"apiKeyRequired":{"type":"boolean"},"physicalSystemConnected":{"type":"boolean"},"deviceControlled":{"type":"boolean"},"networkAccessed":{"type":"boolean"},"confirmedIncidentClaimed":{"type":"boolean"},"findings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"code":{"type":"string"},"subject":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T21:00:00.000Z","status":"detected","itemCount":1,"offlineMinutes":30,"items":[{"id":"iot-behavior-lock_7","detector":"iot-device-behavior-analyze","title":"Unusual IoT device behaviour","status":"signal","observedFacts":["Gap of ≈60 minutes between I1 and I2 (threshold 30m).","Gap of ≈90 minutes between I2 and I3 (threshold 30m).","Device event I3 indicates reboot/offline/config/unexpected behaviour.","Device event I4 indicates reboot/offline/config/unexpected behaviour."],"inferredThreat":"Unusual IoT reporting or control patterns can indicate misconfiguration, fault, or misuse.","confidence":"medium","relatedEventIds":["I1","I2","I3","I4"],"firstAt":"2026-11-04T18:00:00.000Z","lastAt":"2026-11-04T20:31:00.000Z","reasons":["reporting_gap","unexpected_device_event"],"evidence":[{"eventId":"I1","at":"2026-11-04T18:00:00.000Z","fact":"heartbeat; device=lock-7; value=1","inference":"IoT behaviour anomaly only; device was not contacted or controlled.","confidence":"medium"},{"eventId":"I2","at":"2026-11-04T19:00:00.000Z","fact":"heartbeat; device=lock-7; value=1","inference":"IoT behaviour anomaly only; device was not contacted or controlled.","confidence":"medium"},{"eventId":"I3","at":"2026-11-04T20:30:00.000Z","fact":"reboot; device=lock-7; msg=unexpected reboot","inference":"IoT behaviour anomaly only; device was not contacted or controlled.","confidence":"medium"},{"eventId":"I4","at":"2026-11-04T20:31:00.000Z","fact":"config_change; device=lock-7; msg=unauthorized config change","inference":"IoT behaviour anomaly only; device was not contacted or controlled.","confidence":"medium"}],"source":"Caller-supplied IoT telemetry; local behavioural rules","confirmedIncident":false}],"paidProviderUsed":false,"apiKeyRequired":false,"physicalSystemConnected":false,"deviceControlled":false,"networkAccessed":false,"confirmedIncidentClaimed":false,"findings":[{"kind":"conflict","code":"iot_behavior","subject":"lock_7","detail":"IoT behaviour indicators: reporting_gap, unexpected_device_event (confirmedIncident=false)."}],"limitations":["Physical/IoT event logs and telemetry are copied only from caller-supplied fields. Physical security systems are not contacted and devices are never controlled.","Temporal correlation and anomaly rules run locally over supplied records. Missing values are not invented.","Observed facts are separated from inferred threat hypotheses. Anomalies are not labeled confirmed physical incidents without sufficient multi-signal evidence.","Configurable windows/thresholds apply only when supplied; otherwise documented defaults are used.","No paid physical-security feed is used and no API key is required."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{}}]}}},"/api/v1/physical-security/building-security-timeline":{"post":{"operationId":"build_building_security_timeline","summary":"Build building-security timeline","description":"Generate a chronological security timeline from caller-supplied building events. Timeline entries are observed events, not confirmed incidents.","tags":["physical-security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false},"files":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json","application/octet-stream"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000},"role":{"type":"string","maxLength":80}},"required":["fileBase64"],"additionalProperties":false}},"events":{"maxItems":20000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"eventType":{"type":"string","maxLength":120},"category":{"type":"string","enum":["sensor","door","perimeter","camera","alarm","iot","access","other"]},"deviceId":{"type":"string","maxLength":120},"deviceType":{"type":"string","maxLength":80},"zone":{"type":"string","maxLength":120},"building":{"type":"string","maxLength":120},"doorId":{"type":"string","maxLength":120},"cameraId":{"type":"string","maxLength":120},"userId":{"type":"string","maxLength":120},"badgeId":{"type":"string","maxLength":120},"direction":{"type":"string","enum":["in","out","unknown"]},"outcome":{"type":"string","enum":["granted","denied","forced","held","alarm","clear","unknown"]},"value":{"type":"number","minimum":-1000000000,"maximum":1000000000},"unit":{"type":"string","maxLength":40},"baseline":{"type":"number","minimum":-1000000000,"maximum":1000000000},"threshold":{"type":"number","minimum":-1000000000,"maximum":1000000000},"severity":{"type":"string","maxLength":40},"message":{"type":"string","maxLength":4000},"labels":{"maxItems":40,"type":"array","items":{"type":"string","maxLength":80}},"relatedEventIds":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":80}},"source":{"type":"string","maxLength":200}},"additionalProperties":false}},"asOf":{"type":"string","maxLength":40},"anomalyStdev":{"type":"number","minimum":1,"maximum":10},"doorWindowMinutes":{"type":"number","minimum":1,"maximum":10080},"tailgateSeconds":{"type":"number","minimum":1,"maximum":600},"correlationWindowMinutes":{"type":"number","minimum":1,"maximum":1440},"offlineMinutes":{"type":"number","minimum":1,"maximum":10080}},"additionalProperties":false},"example":{"asOf":"2026-11-04T21:00:00.000Z","events":[{"id":"E1","at":"2026-11-04T19:50:00.000Z","building":"HQ","zone":"lobby","category":"door","doorId":"lobby","eventType":"access","outcome":"denied","severity":"medium","source":"Caller-supplied"},{"id":"E2","at":"2026-11-04T19:55:00.000Z","building":"HQ","zone":"lobby","category":"camera","cameraId":"cam-lobby","eventType":"tamper","message":"lens covered","severity":"high","source":"Caller-supplied"},{"id":"E3","at":"2026-11-04T20:00:00.000Z","building":"HQ","zone":"lobby","category":"alarm","deviceId":"panel-1","eventType":"intrusion_alarm","outcome":"alarm","severity":"high","source":"Caller-supplied"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"eventCount":{"type":"number"},"sections":{"type":"array","items":{"type":"object","properties":{"building":{"type":"string"},"eventCount":{"type":"number"},"firstAt":{"type":"string"},"lastAt":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}}},"additionalProperties":true}},"timeline":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"number"},"eventId":{"type":"string"},"at":{"type":"string"},"building":{"type":"string"},"zone":{"type":"string"},"category":{"type":"string"},"eventType":{"type":"string"},"deviceId":{"type":"string"},"outcome":{"type":"string"},"severity":{"type":"string"},"summary":{"type":"string"},"confirmedIncident":{"type":"boolean"},"source":{"type":"string"}},"additionalProperties":true}},"paidProviderUsed":{"type":"boolean"},"apiKeyRequired":{"type":"boolean"},"physicalSystemConnected":{"type":"boolean"},"deviceControlled":{"type":"boolean"},"networkAccessed":{"type":"boolean"},"confirmedIncidentClaimed":{"type":"boolean"},"findings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"code":{"type":"string"},"subject":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T21:00:00.000Z","status":"reported","eventCount":3,"sections":[{"building":"hq","eventCount":3,"firstAt":"2026-11-04T19:50:00.000Z","lastAt":"2026-11-04T20:00:00.000Z","categories":["door","camera","alarm"]}],"timeline":[{"sequence":1,"eventId":"E1","at":"2026-11-04T19:50:00.000Z","building":"HQ","zone":"lobby","category":"door","eventType":"access","deviceId":"lobby","outcome":"denied","severity":"medium","summary":"access; door=lobby; zone=lobby; outcome=denied","confirmedIncident":false,"source":"Caller-supplied"},{"sequence":2,"eventId":"E2","at":"2026-11-04T19:55:00.000Z","building":"HQ","zone":"lobby","category":"camera","eventType":"tamper","deviceId":"cam-lobby","outcome":"unknown","severity":"high","summary":"tamper; camera=cam-lobby; zone=lobby; msg=lens covered","confirmedIncident":false,"source":"Caller-supplied"},{"sequence":3,"eventId":"E3","at":"2026-11-04T20:00:00.000Z","building":"HQ","zone":"lobby","category":"alarm","eventType":"intrusion_alarm","deviceId":"panel-1","outcome":"alarm","severity":"high","summary":"intrusion_alarm; device=panel-1; zone=lobby; outcome=alarm","confirmedIncident":false,"source":"Caller-supplied"}],"paidProviderUsed":false,"apiKeyRequired":false,"physicalSystemConnected":false,"deviceControlled":false,"networkAccessed":false,"confirmedIncidentClaimed":false,"findings":[{"kind":"observation","code":"timeline_built","subject":"","detail":"Timeline includes 3 security-relevant event(s); none are confirmed incidents."}],"limitations":["Physical/IoT event logs and telemetry are copied only from caller-supplied fields. Physical security systems are not contacted and devices are never controlled.","Temporal correlation and anomaly rules run locally over supplied records. Missing values are not invented.","Observed facts are separated from inferred threat hypotheses. Anomalies are not labeled confirmed physical incidents without sufficient multi-signal evidence.","Configurable windows/thresholds apply only when supplied; otherwise documented defaults are used.","No paid physical-security feed is used and no API key is required."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}}]}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}