{
  "openapi": "3.1.0",
  "info": {
    "title": "CyberLetics Ingest API",
    "version": "1.0.0",
    "summary": "Send device telemetry, file hashes and security alerts to CyberLetics.",
    "description": "The API the CyberLetics device agent uses, open to your own scripts and tools. Every request is authenticated with an API key created in Settings → API Keys and sent in the `X-API-Key` header. Calls made with each key are counted per calendar month (UTC) and shown next to the key in Settings.\n\nKeep keys secret: a key can report devices and raise alerts for your whole organisation. Revoke a key in Settings the moment it might have leaked.",
    "contact": { "name": "CyberLetics support", "email": "hello@cyberletics.in", "url": "https://cyberletics.in/contact" }
  },
  "servers": [{ "url": "https://cyberletics.onrender.com/api", "description": "Production" }],
  "security": [{ "ApiKey": [] }],
  "tags": [
    { "name": "Devices", "description": "Register a device and report its security posture." },
    { "name": "Files", "description": "Check file hashes against VirusTotal." },
    { "name": "Alerts", "description": "Raise alerts from your own monitoring." }
  ],
  "paths": {
    "/ingest/telemetry": {
      "post": {
        "tags": ["Devices"],
        "operationId": "sendTelemetry",
        "summary": "Report a device check-in",
        "description": "Creates the device on its first check-in and updates it afterwards. Devices are matched by `macAddress` when you send one, otherwise by `hostname`. A device that stops checking in for 24 hours is marked inactive and raises one alert.\n\nA new device counts toward your plan's device limit (Starter 10, Shield 50, Fortress 200, trial 1). Past the limit the call returns `403 DEVICE_LIMIT_REACHED`.",
        "requestBody": {
          "required": true,
          "content": { "application/json": {
            "schema": { "$ref": "#/components/schemas/Telemetry" },
            "example": {
              "hostname": "finance-laptop-03", "ipAddress": "192.168.1.24", "macAddress": "3C:22:FB:1A:9E:07",
              "os": "windows", "osVersion": "11 23H2", "deviceType": "laptop",
              "antivirusInstalled": true, "firewallEnabled": true, "diskEncrypted": false,
              "pendingUpdatesCount": 3, "lastPatched": "2026-11-10T04:30:00Z"
            }
          } }
        },
        "responses": {
          "200": { "description": "Device created or updated.", "content": { "application/json": {
            "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "device": { "$ref": "#/components/schemas/Device" } } } } }
          } } },
          "400": { "$ref": "#/components/responses/ValidationError" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/SubscriptionInactive" },
          "403": { "$ref": "#/components/responses/LimitReached" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/ingest/scan": {
      "post": {
        "tags": ["Files"],
        "operationId": "scanFileHashes",
        "summary": "Check file hashes for malware",
        "description": "Looks up 1 to 50 SHA-256 hashes on VirusTotal. A hash flagged as malicious raises a `MALWARE_DETECTED` alert on the device. Lookups share a per-organisation hourly budget; when it runs out the response says `skipped: true` with a reason instead of guessing.",
        "requestBody": {
          "required": true,
          "content": { "application/json": {
            "schema": { "$ref": "#/components/schemas/ScanRequest" },
            "example": { "deviceId": "6f1c2a4e-8d3b-4f5a-9c7e-2b1d0a9e8f71", "hashes": [{ "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "path": "C:\\Users\\asha\\Downloads\\invoice.exe" }] }
          } }
        },
        "responses": {
          "200": { "description": "Lookup finished (or skipped, with the reason).", "content": { "application/json": {
            "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/ScanResult" } } }
          } } },
          "400": { "$ref": "#/components/responses/ValidationError" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/SubscriptionInactive" },
          "404": { "description": "No device with that id in your organisation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/ingest/webhooks/alerts": {
      "post": {
        "tags": ["Alerts"],
        "operationId": "createAlert",
        "summary": "Raise an alert",
        "description": "Creates an alert in your Alerts list and pushes it to open dashboards. If an alert of the same type for the same device is already open or acknowledged, that alert is returned instead of a duplicate.",
        "requestBody": {
          "required": true,
          "content": { "application/json": {
            "schema": { "$ref": "#/components/schemas/AlertRequest" },
            "example": { "alertType": "BRUTE_FORCE_ATTEMPT", "severity": "HIGH", "title": "42 failed SSH logins in 5 minutes", "description": "Failed logins for root from 203.0.113.9 on web-01.", "sourceIp": "203.0.113.9" }
          } }
        },
        "responses": {
          "200": { "description": "Alert created, or the matching open alert.", "content": { "application/json": {
            "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "alert": { "$ref": "#/components/schemas/Alert" } } } } }
          } } },
          "400": { "$ref": "#/components/responses/ValidationError" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/SubscriptionInactive" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Create one in Settings → API Keys. It starts with `cl_` and is shown once." }
    },
    "schemas": {
      "Telemetry": {
        "type": "object",
        "required": ["hostname", "ipAddress", "os", "osVersion", "deviceType"],
        "properties": {
          "hostname": { "type": "string", "maxLength": 253 },
          "ipAddress": { "type": "string", "description": "IPv4 or IPv6 address." },
          "macAddress": { "type": "string", "description": "Optional. When sent, devices are matched on it instead of hostname." },
          "os": { "type": "string", "enum": ["windows", "macos", "darwin", "linux", "ios", "android"] },
          "osVersion": { "type": "string" },
          "deviceType": { "type": "string", "enum": ["laptop", "desktop", "server", "mobile", "router", "printer", "iot"] },
          "antivirusInstalled": { "type": "boolean" },
          "firewallEnabled": { "type": "boolean" },
          "diskEncrypted": { "type": "boolean" },
          "pendingUpdatesCount": { "type": "integer", "minimum": 0 },
          "lastPatched": { "type": ["string", "null"], "format": "date-time" },
          "posture": { "type": ["object", "null"], "description": "Extra posture checks the agent collects. Unknown keys are dropped.", "additionalProperties": true }
        }
      },
      "Device": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "hostname": { "type": "string" },
          "os": { "type": "string", "enum": ["WINDOWS", "MACOS", "LINUX", "IOS", "ANDROID"] },
          "status": { "type": "string" },
          "lastSeen": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": true
      },
      "ScanRequest": {
        "type": "object",
        "required": ["deviceId", "hashes"],
        "properties": {
          "deviceId": { "type": "string", "format": "uuid", "description": "The `device.id` returned by /ingest/telemetry." },
          "hashes": { "type": "array", "minItems": 1, "maxItems": 50, "items": {
            "type": "object", "required": ["sha256", "path"],
            "properties": { "sha256": { "type": "string", "minLength": 64, "maxLength": 64 }, "path": { "type": "string" } }
          } }
        }
      },
      "ScanResult": {
        "type": "object",
        "properties": {
          "maliciousHits": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "alert": { "$ref": "#/components/schemas/Alert" },
          "skipped": { "type": "boolean" },
          "reason": { "type": "string", "enum": ["ORG_QUOTA_EXCEEDED", "VT_QUOTA_EXHAUSTED"] }
        }
      },
      "AlertRequest": {
        "type": "object",
        "required": ["alertType", "severity", "title", "description"],
        "properties": {
          "alertType": { "type": "string", "enum": ["PHISHING_ATTEMPT", "BRUTE_FORCE_ATTEMPT", "OS_UPDATE_REQUIRED", "UNUSUAL_DATA_EXPORT", "MALWARE_DETECTED", "UNAUTHORIZED_ACCESS", "SUSPICIOUS_LOGIN", "RANSOMWARE_DETECTED", "PORT_SCAN_DETECTED", "DATA_EXFILTRATION", "WEAK_PASSWORD_DETECTED", "CERTIFICATE_EXPIRED"] },
          "severity": { "type": "string", "enum": ["LOW", "MEDIUM", "HIGH", "CRITICAL"] },
          "title": { "type": "string", "maxLength": 255 },
          "description": { "type": "string" },
          "sourceIp": { "type": ["string", "null"] },
          "deviceId": { "type": ["string", "null"], "format": "uuid" }
        }
      },
      "Alert": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "alertType": { "type": "string" },
          "severity": { "type": "string", "enum": ["LOW", "MEDIUM", "HIGH", "CRITICAL"] },
          "title": { "type": "string" },
          "status": { "type": "string", "enum": ["OPEN", "ACKNOWLEDGED", "RESOLVED", "FALSE_POSITIVE"] },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": true
      },
      "Error": {
        "type": "object",
        "properties": {
          "success": { "const": false },
          "message": { "type": "string" },
          "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }
        }
      }
    },
    "responses": {
      "ValidationError": { "description": "A field is missing or invalid. `error.details` lists each one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Validation failed.", "error": { "code": "VALIDATION_ERROR", "message": "Validation failed.", "details": [{ "path": "ipAddress", "msg": "Invalid value" }] } } } } },
      "Unauthorized": { "description": "`MISSING_API_KEY` or `INVALID_API_KEY` (unknown or revoked).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "SubscriptionInactive": { "description": "The organisation's trial has ended or its subscription is suspended or cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "LimitReached": { "description": "`DEVICE_LIMIT_REACHED`: a new device would go past the plan's device limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Too many requests from one IP address (by default 100 per 15 minutes). The `RateLimit-*` response headers say how many remain and when the window resets." }
    }
  }
}
