openapi: 3.1.0
info:
  title: Cyber Security House — Connected World & Enterprise Platform API
  version: 5.0.0
  description: >
    Versioned REST API (/api/v1) for Cyber Security House, operated by ARYA AI TECHNOLOGY LTD (Company No. 17372232, England and Wales, United Kingdom).
    Enforces multi-tenant isolation (PostgreSQL 16 FORCE RLS + authenticated membership binding),
    RFC 9457 Problem Details errors, idempotent event ingestion, deterministic Sigma detection,
    CSH AI GUARD policy evaluation, ARYA SAI redacted advisory analysis, and Connected World v5.0 guardrails.
  contact:
    name: ARYA AI TECHNOLOGY LTD (Company No. 17372232, England and Wales, United Kingdom) — London Global Operations
    url: https://www.cybersecurityhouse.com/trust
    email: security@cybersecurityhouse.com
servers:
  - url: https://api.cybersecurityhouse.com
    description: UK Production Control & Data Plane
  - url: http://localhost:8000
    description: Local Development Modular Monolith
paths:
  /api/v1/health/live:
    get:
      summary: Liveness probe
      operationId: getHealthLive
      responses:
        "200":
          description: Service is alive
  /api/v1/health/ready:
    get:
      summary: Readiness probe verifying RLS and adapter state
      operationId: getHealthReady
      responses:
        "200":
          description: Service is ready
  /api/v1/public/leads:
    post:
      summary: Submit public marketing lead or service inquiry
      operationId: submitPublicLead
      responses:
        "201":
          description: Lead validated and persisted to Company Operations CRM
        "400":
          description: Anti-spam honeypot triggered (RFC 9457 Problem Details)
  /api/v1/public/demo-requests:
    post:
      summary: Request a scoped product demonstration
      operationId: submitDemoRequest
      responses:
        "201":
          description: Demo request persisted to CRM
  /api/v1/organizations/{org_id}/assets:
    get:
      summary: List tenant-scoped assets
      operationId: listTenantAssets
      responses:
        "200":
          description: Tenant asset list
        "403":
          description: Cross-tenant isolation violation
    post:
      summary: Register a new asset requiring cryptographic ownership verification
      operationId: registerTenantAsset
      responses:
        "201":
          description: Asset registered in pending verification state
  /api/v1/organizations/{org_id}/assets/{asset_id}/verify:
    post:
      summary: Verify cryptographic domain/host ownership before scan or ingestion
      operationId: verifyAssetOwnership
      responses:
        "200":
          description: Asset marked verified
  /api/v1/organizations/{org_id}/events/ingest:
    post:
      summary: Ingest normalized telemetry event with idempotency and Sigma rule evaluation
      operationId: ingestSecurityEvent
      responses:
        "201":
          description: Event ingested or idempotently deduplicated; returns triggered alert if matched
        "403":
          description: Cross-tenant violation
        "409":
          description: Asset ownership unverified
  /api/v1/organizations/{org_id}/alerts/{alert_id}/analyze-arya-sai:
    post:
      summary: Generate redacted, confidence-calibrated ARYA SAI advisory analysis for an alert
      operationId: analyzeAlertWithAryaSai
      responses:
        "200":
          description: Structured advisory output with human_approval_required=true
  /api/v1/organizations/{org_id}/ai/evaluate:
    post:
      summary: Evaluate autonomous AI agent tool call or prompt against CSH AI GUARD policy engine
      operationId: evaluateAiGuardPolicy
      responses:
        "200":
          description: Deterministic allow, block, or require_approval decision with DLP redaction
  /api/v1/webhooks/billing:
    post:
      summary: Process HMAC-SHA256 signed billing webhook with 300s replay window protection
      operationId: handleBillingWebhook
      responses:
        "200":
          description: Webhook verified and idempotently processed
        "401":
          description: Invalid HMAC signature or stale timestamp
  /api/v1/products:
    get:
      summary: List all 15 sellable Connected World v5.0 products and integration maturity states
      operationId: listSellableProducts
      responses:
        "200":
          description: Catalogue of 15 sellable products
  /api/v1/sectors:
    get:
      summary: List all 11 industry sector packs and mapped regulatory frameworks
      operationId: listSectorPacks
      responses:
        "200":
          description: Catalogue of 11 sector packs
  /api/v1/organizations/{org_id}/households/{household_id}/discover:
    post:
      summary: CSH HOME SHIELD consent-verified passive LAN discovery (unsupported devices return unknown, never secure)
      operationId: discoverHouseholdDevices
      responses:
        "200":
          description: Confidence-scored device inventory with privacy stream collection blocked
        "400":
          description: Privacy boundary violation (camera/audio/lock-code payload rejected)
        "422":
          description: Homeowner consent or ownership verification missing
  /api/v1/organizations/{org_id}/charge-points/{cp_id}/ocpp-events:
    post:
      summary: CSH EV SHIELD read-only OCPP 1.6J/2.0.1 security event ingestion and outage correlation
      operationId: ingestOcppSecurityEvent
      responses:
        "201":
          description: OCPP security event evaluated in read-only mode
  /api/v1/organizations/{org_id}/charge-points/{cp_id}/command:
    post:
      summary: CSH EV SHIELD safety guardrail endpoint (blocks physical charger/contactor/BMS actuation with HTTP 403)
      operationId: evaluateChargePointCommand
      responses:
        "200":
          description: Read-only telemetry query permitted
        "403":
          description: Physical or safety-critical actuation blocked by EV-SAFE-001 policy
  /api/v1/organizations/{org_id}/resilience/exercises:
    post:
      summary: CSH RESILIENCE Business Impact Analysis (BIA) backup restore verification drill
      operationId: verifyResilienceExercise
      responses:
        "201":
          description: Cryptographic RTO/RPO drill attestation recorded
  /api/v1/organizations/{org_id}/privacy/export:
    get:
      summary: UK GDPR / KVKK verifiable cryptographic privacy and telemetry export
      operationId: exportTenantPrivacyData
      responses:
        "200":
          description: SHA-256 integrity-attested customer privacy package
        "403":
          description: Cross-tenant isolation violation
  /api/v1/organizations/{org_id}/households/{household_id}/transfer-ownership:
    post:
      summary: Transfer household ownership upon tenancy change or property sale
      operationId: transferHouseholdOwnership
      responses:
        "200":
          description: Household ownership transferred with verified consent revocation
  /api/v1/organizations/{org_id}/scans:
    post:
      summary: Run ownership-verified exposure scan (blocks active scans on OT/IoMT assets with HTTP 403)
      operationId: executeExposureScan
      responses:
        "200":
          description: Passive external exposure assessment completed
        "403":
          description: Active/intrusive scan rejected on OT or medical asset by OT-SAFETY-001 policy
  /api/v1/organizations/{org_id}/entitlements:
    get:
      summary: List active purchased product entitlements for an SME organization
      operationId: listOrganizationEntitlements
      responses:
        "200":
          description: List of active product entitlements
        "403":
          description: Cross-tenant isolation violation
    post:
      summary: Update active product entitlements (10 products) with PostgreSQL 16 FORCE RLS
      operationId: updateOrganizationEntitlements
      responses:
        "200":
          description: Product entitlements updated live
        "403":
          description: Insufficient permissions
  /api/v1/nexus/grants:
    get:
      summary: List Innovate UK 6+1 R&D Grant Portfolio, budgets, sprint phases, and validated metrics
      operationId: listNexusGrants
      responses:
        "200":
          description: 6+1 R&D Grants Portfolio ledger
  /api/v1/aie/adaptive-learn/evaluate:
    post:
      summary: ARYA AIE LEARN Continual Learning & Uncertainty Quantification (UQ) engine evaluation
      operationId: evaluateAdaptiveLearn
      responses:
        "200":
          description: Uncertainty score, Brier metric, and dynamic retraining decision
  /api/v1/aie/digital-twin/simulate:
    post:
      summary: ARYA Digital Twin Maritime & Industrial CPS mesh scenario simulation
      operationId: simulateDigitalTwin
      responses:
        "200":
          description: Simulated mesh nodes, latency metrics, and cascade risk prediction
  /api/v1/aie/agri-ai/telemetry:
    post:
      summary: ARYA AgriAI Lab smart irrigation and precision soil moisture telemetry evaluation
      operationId: evaluateAgriAiTelemetry
      responses:
        "200":
          description: Soil moisture evaluation, water savings metric, and valve actuation schedule