{
  "openapi": "3.1.0",
  "info": {
    "title": "SentrySurface Platform API",
    "version": "1.1.0",
    "description": "Multi-signal phishing, AiTM credential harvester, crypto-drainer, and scam intelligence API with OASIS STIX 2.1, TAXII 2.1, Streamable HTTP MCP (11 tools), Customer IDR/EDR Dispute Operations, and 6-jurisdiction statutory ASI compliance (AU SPF, SG SRF, UK PSR/OSA, EU DSA, US FCC/FinCEN, INTERPOL I-GRIP).",
    "contact": {
      "name": "SentrySurface Security & Platform Engineering",
      "url": "https://sentrysurface.io/developers"
    }
  },
  "servers": [
    {
      "url": "https://sentrysurface.io",
      "description": "Production Cloudflare Edge"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Scans",
      "description": "URL & multi-signal threat analysis, SSE streaming, drift diffs, and R2 forensic artifacts"
    },
    {
      "name": "Workspace",
      "description": "Command Center KPIs, prioritized Action Items, and Maker-Checker dual-control governance"
    },
    {
      "name": "Intelligence",
      "description": "Concurrent Batch URL scanning, Brand Typosquat Watchlist, and Lakehouse NL-to-SQL Threat Hunter"
    },
    {
      "name": "Operations",
      "description": "Automated Registrar/ASN Takedowns, Customer Scam Complaints (IDR/EDR), CRM Bridges, and Public Branded Intake"
    },
    {
      "name": "Compliance & TAXII",
      "description": "Statutory ASI dossiers, Ombudsman Dispute Defense Packs, STIX 2.1, OASIS TAXII 2.1, and SOC 2 Audit Logs"
    },
    {
      "name": "MCP Server",
      "description": "Native Streamable HTTP Model Context Protocol (JSON-RPC 2.0) for Claude, Cursor, and autonomous SOC agents"
    },
    {
      "name": "Admin & Billing",
      "description": "Regulated Onboarding, Organization RBAC, SHA-256 API Keys, Session Identity, and Stripe Billing"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key (sk_live_sentry_...)",
        "description": "SHA-256 hashed workspace API key minted in /developers (or active Clerk workspace session cookie)."
      }
    },
    "parameters": {
      "SubmissionIdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Scan submission identifier (e.g. ss-evilginx-m365-991a)",
        "schema": {
          "type": "string",
          "example": "ss-evilginx-m365-991a"
        }
      },
      "FrameworkQueryParam": {
        "name": "framework",
        "in": "query",
        "required": false,
        "description": "Statutory scam/compliance regime code",
        "schema": {
          "$ref": "#/components/schemas/RegulatoryFramework"
        }
      },
      "SectorQueryParam": {
        "name": "sector",
        "in": "query",
        "required": false,
        "description": "Regulated industry sector",
        "schema": {
          "$ref": "#/components/schemas/RegulatedSector"
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "example": "Authentication required"
          },
          "requires_auth": {
            "type": "boolean"
          },
          "required_role": {
            "type": "string"
          },
          "required_plan": {
            "type": "string"
          }
        }
      },
      "RegulatoryFramework": {
        "type": "string",
        "enum": [
          "AU_SPF",
          "SG_SRF",
          "UK_OSA_APP",
          "EU_DSA",
          "US_FCC_FINCEN",
          "INTERPOL_IGRIP"
        ],
        "default": "AU_SPF"
      },
      "RegulatedSector": {
        "type": "string",
        "enum": [
          "banking_finance",
          "telecommunications",
          "digital_platform",
          "enterprise_brand"
        ],
        "default": "banking_finance"
      },
      "ScanRequest": {
        "type": "object",
        "description": "Submit either a direct `url` or a raw `sms_body` containing an embedded scam URL.",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com"
          },
          "mode": {
            "type": "string",
            "enum": ["fast", "stealth", "deep_recon"],
            "default": "stealth",
            "description": "Execution tier: fast (1 credit, synchronous Edge Browser), stealth (3 credits, warm sandbox), or deep_recon (10 credits, passive CVE + phishing kit recon)."
          },
          "visibility": {
            "type": "string",
            "enum": ["public", "private"],
            "default": "public",
            "description": "Private scans are tenant-isolated to the caller's org_id (requires Pro/Team/Regulated plan)."
          },
          "force_rescan": {
            "type": "boolean",
            "default": false,
            "description": "Bypass the 15-minute Edge verdict cache and force fresh execution."
          },
          "sms_body": {
            "type": "string",
            "description": "Optional SMS/WhatsApp scam lure text (embedded URLs & callback CLIs are automatically extracted and PII-scrubbed)."
          },
          "sms_sender_id": {
            "type": "string",
            "description": "Optional spoofed alphanumeric SMS Sender ID (ACMA / IMDA)."
          },
          "callback_phone": {
            "type": "string",
            "description": "Optional vishing callback phone number / CLI."
          },
          "payee_account_or_wallet": {
            "type": "string",
            "description": "Optional mule bank account (BSB/IBAN/Sort Code) or 0x crypto wallet."
          },
          "payee_name": {
            "type": "string",
            "description": "Optional claimed beneficiary name (Confirmation of Payee)."
          },
          "advertiser_id": {
            "type": "string",
            "description": "Optional paid-ad advertiser ID (EU DSA Art. 26 / UK OSA / ACCC AIV)."
          },
          "ad_network": {
            "type": "string",
            "description": "Optional ad network source (e.g. Meta Ads Library, Google Ads)."
          }
        }
      },
      "ScanVerdictSummary": {
        "type": "object",
        "properties": {
          "submission_id": { "type": "string", "example": "ss-evilginx-m365-991a" },
          "target_url": { "type": "string", "format": "uri" },
          "status": { "type": "string", "enum": ["queued", "running", "completed", "failed"] },
          "threat_level": { "type": "string", "enum": ["clean", "low", "suspicious", "malicious"] },
          "risk_score": { "type": "number", "minimum": 0, "maximum": 100, "example": 96 },
          "verdict_scam_type": { "type": ["string", "null"], "example": "aitm_credential_harvester" },
          "mode": { "type": "string", "enum": ["fast", "stealth", "deep_recon"] },
          "visibility": { "type": "string", "enum": ["public", "private"] },
          "credits_charged": { "type": "integer", "example": 1 },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "WorkspaceOverviewMutation": {
        "type": "object",
        "required": ["action"],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "update_action_state",
              "create_maker_checker",
              "review_maker_checker"
            ],
            "example": "update_action_state"
          },
          "action_key": {
            "type": "string",
            "description": "Required when action is update_action_state.",
            "example": "onboard-connector-setup"
          },
          "status": {
            "type": "string",
            "enum": ["open", "snoozed", "resolved", "dismissed"],
            "description": "Target state when action is update_action_state."
          },
          "snooze_hours": {
            "type": "integer",
            "minimum": 1,
            "default": 24,
            "description": "Snooze duration in hours when status is snoozed."
          },
          "note": {
            "type": "string",
            "description": "Optional operator audit note when updating an action item."
          },
          "action_type": {
            "type": "string",
            "enum": [
              "takedown_dispatch",
              "compliance_asi_release",
              "complaint_settlement"
            ],
            "description": "Dual-control request category when action is create_maker_checker."
          },
          "target_id": {
            "type": "string",
            "description": "Target entity ID (submission_id, case_id, or complaint_id) for create_maker_checker."
          },
          "title": {
            "type": "string",
            "description": "Human-readable approval summary title for create_maker_checker."
          },
          "summary": {
            "type": "string"
          },
          "payload": {
            "type": "object",
            "additionalProperties": true
          },
          "request_id": {
            "type": "string",
            "description": "Maker-Checker request ID when action is review_maker_checker."
          },
          "decision": {
            "type": "string",
            "enum": ["approved", "rejected"],
            "description": "Approver decision when action is review_maker_checker (enforces Two-Person Rule)."
          },
          "review_note": {
            "type": "string",
            "description": "Optional Compliance Officer / Admin sign-off note."
          }
        }
      },
      "BatchScanRequest": {
        "type": "object",
        "required": ["items"],
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 25,
            "description": "Up to 25 URLs, raw SMS scam texts, or structured multi-signal objects.",
            "items": {
              "oneOf": [
                { "type": "string", "example": "https://example.com" },
                { "$ref": "#/components/schemas/ScanRequest" }
              ]
            }
          },
          "mode": {
            "type": "string",
            "enum": ["fast", "stealth", "deep_recon"],
            "default": "fast"
          },
          "visibility": {
            "type": "string",
            "enum": ["public", "private"],
            "default": "private"
          }
        }
      },
      "BrandCreateRequest": {
        "type": "object",
        "required": ["brand_name", "official_domains"],
        "properties": {
          "brand_name": { "type": "string", "example": "Acme Bank" },
          "official_domains": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["acmebank.com.au", "acmebank.com"]
          },
          "logo_phash": {
            "type": "string",
            "description": "Optional 64-bit perceptual hash hex string for visual brand clone matching."
          },
          "monitoring_interval": {
            "type": "string",
            "enum": ["hourly", "daily", "weekly"],
            "default": "daily"
          }
        }
      },
      "BrandPatchRequest": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": ["run_sweep", "update_schedule"],
            "default": "run_sweep"
          },
          "brand_id": {
            "type": "string",
            "description": "Target brand_id (optional for run_sweep across all brands; required for update_schedule)."
          },
          "monitoring_interval": {
            "type": "string",
            "enum": ["hourly", "daily", "weekly"]
          }
        }
      },
      "QueryRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {
            "type": "string",
            "example": "Show all malicious scans in the last 7 days"
          },
          "preset": {
            "type": "string",
            "description": "Optional named analytical query preset."
          }
        }
      },
      "TakedownRequest": {
        "type": "object",
        "required": ["submission_id", "target_url"],
        "properties": {
          "submission_id": { "type": "string", "example": "ss-evilginx-m365-991a" },
          "target_url": { "type": "string", "format": "uri", "example": "https://login-micros0ft-auth-portal.com" },
          "target_brand": { "type": "string", "example": "Microsoft 365" },
          "registrar": { "type": "string", "example": "Namecheap" },
          "asn": { "type": "string", "example": "AS13335" },
          "scam_type": { "type": "string", "example": "aitm_credential_harvester" },
          "escalation_level": {
            "type": "string",
            "enum": ["standard", "urgent", "regulator_backed"],
            "default": "standard"
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "description": "Optional SOAR callback HTTPS URL."
          }
        }
      },
      "TakedownPatchRequest": {
        "type": "object",
        "required": ["case_id"],
        "properties": {
          "case_id": { "type": "string", "example": "TD-20261118-991A" },
          "status": {
            "type": "string",
            "enum": [
              "pending_approval",
              "dispatched",
              "acknowledged",
              "mitigating",
              "defanged",
              "rejected"
            ]
          },
          "verify_defanged": {
            "type": "boolean",
            "default": false,
            "description": "When true, runs a live Edge DNS/HTTP probe to confirm HTTP 404/410 or NXDOMAIN defanging."
          },
          "note": { "type": "string" }
        }
      },
      "ComplaintCreateRequest": {
        "type": "object",
        "properties": {
          "external_ticket_ref": { "type": "string", "example": "ZD-49201" },
          "reporter_channel": {
            "type": "string",
            "enum": [
              "sms",
              "whatsapp",
              "phone_call",
              "email",
              "paid_ad",
              "website",
              "qr_code"
            ],
            "default": "sms"
          },
          "dispute_classification": {
            "type": "string",
            "enum": ["authorized_app", "unauthorized_ato", "no_loss_feedback"],
            "default": "authorized_app"
          },
          "claimed_loss_amount": { "type": "number", "default": 0, "example": 2450 },
          "claimed_loss_currency": { "type": "string", "example": "AUD" },
          "suspect_url": { "type": "string", "format": "uri" },
          "sms_body": { "type": "string" },
          "sms_sender_id": { "type": "string" },
          "callback_phone": { "type": "string" },
          "payee_account_or_wallet": { "type": "string" },
          "advertiser_id": { "type": "string" },
          "customer_narrative": {
            "type": "string",
            "description": "Customer narrative (PANs, OTPs, emails, and query tokens are automatically scrubbed)."
          },
          "submission_id": { "type": "string" },
          "framework": { "$ref": "#/components/schemas/RegulatoryFramework" }
        }
      },
      "ComplaintPatchRequest": {
        "type": "object",
        "required": ["status"],
        "properties": {
          "complaint_id": { "type": "string", "example": "CMP-20261118-A1B2C" },
          "campaign_cluster_key": {
            "type": "string",
            "description": "Bulk-transition all complaints in a deduplicated scam campaign cluster."
          },
          "status": {
            "type": "string",
            "enum": [
              "triaging",
              "investigating",
              "stop_clock_paused",
              "pending_settlement_approval",
              "reimbursed",
              "partially_settled",
              "declined_safe_harbor",
              "defanged_resolved"
            ]
          },
          "resolution_notes": { "type": "string" },
          "external_ticket_ref": { "type": "string" }
        }
      },
      "ComplaintConfigPatchRequest": {
        "type": "object",
        "properties": {
          "org_slug": { "type": "string", "example": "acme-bank" },
          "public_intake_enabled": { "type": "boolean" },
          "brand_display_name": { "type": "string", "example": "Acme Bank Scam & Dispute Desk" },
          "official_domains": {
            "type": "array",
            "items": { "type": "string" }
          },
          "support_contact_email": { "type": "string", "format": "email" },
          "custom_intake_banner": { "type": "string" },
          "default_framework": { "$ref": "#/components/schemas/RegulatoryFramework" },
          "default_currency": { "type": "string", "example": "AUD" },
          "auto_scan_mode": { "type": "string", "enum": ["fast", "stealth"] },
          "auto_stage_takedown": { "type": "boolean" },
          "auto_stage_min_risk": { "type": "integer", "minimum": 0, "maximum": 100 },
          "require_maker_checker_settlement": { "type": "boolean" },
          "crm_preset": {
            "type": "string",
            "enum": [
              "none",
              "zendesk",
              "salesforce_service_cloud",
              "servicenow_csm",
              "freshdesk",
              "jira_service_management",
              "custom_webhook"
            ]
          },
          "crm_webhook_url": { "type": "string", "format": "uri" },
          "crm_auth_header": { "type": "string" },
          "clear_crm_auth_header": { "type": "boolean" },
          "rotate_hmac_secret": { "type": "boolean" }
        }
      },
      "ComplianceDispatchRequest": {
        "type": "object",
        "properties": {
          "framework": { "$ref": "#/components/schemas/RegulatoryFramework" },
          "sector": { "$ref": "#/components/schemas/RegulatedSector" },
          "webhook_url": { "type": "string", "format": "uri" },
          "compliance_email": { "type": "string", "format": "email" },
          "officer_certified": { "type": "boolean", "default": false }
        }
      },
      "ComplianceLifecyclePatchRequest": {
        "type": "object",
        "properties": {
          "framework": { "$ref": "#/components/schemas/RegulatoryFramework" },
          "sector": { "$ref": "#/components/schemas/RegulatedSector" },
          "event_type": {
            "type": "string",
            "enum": [
              "SUPPLEMENTARY_IOC_DRIFT",
              "TAKEDOWN_DEFANGED_UPDATE",
              "PSR_STOP_THE_CLOCK_INVOKED",
              "DORA_INTERMEDIATE_72H_REPORT",
              "INBOUND_REGULATOR_ENRICHMENT",
              "INBOUND_DISPUTE_QUERY",
              "COUNTERPARTY_BANK_FREEZE_ACK",
              "REGULATOR_ACK"
            ],
            "default": "SUPPLEMENTARY_IOC_DRIFT"
          },
          "note": { "type": "string" },
          "external_regulator_ref": { "type": "string" }
        }
      },
      "McpJsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"], "default": "2.0" },
          "id": {
            "oneOf": [{ "type": "integer" }, { "type": "string" }],
            "example": 1
          },
          "method": {
            "type": "string",
            "enum": ["initialize", "tools/list", "tools/call"],
            "example": "tools/list"
          },
          "params": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "enum": [
                  "analyze_url",
                  "compare_scan_diff",
                  "get_scan_result",
                  "get_webscan_data",
                  "lookup_domain_reputation",
                  "sentrysurface_trigger_takedown",
                  "sentrysurface_verify_defanging",
                  "sentrysurface_generate_compliance_asi",
                  "sentrysurface_update_compliance_lifecycle",
                  "sentrysurface_log_customer_complaint",
                  "sentrysurface_list_customer_complaints"
                ]
              },
              "arguments": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "ApiKeyCreateRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "default": "Production Key",
            "example": "Splunk SOAR Production"
          },
          "prefix_style": {
            "type": "string",
            "enum": ["sk", "ss"],
            "default": "sk"
          }
        }
      },
      "OrgMemberUpsertRequest": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "email": { "type": "string", "format": "email", "example": "secops@acmebank.com" },
          "display_name": { "type": "string", "example": "Alex Chen" },
          "role": {
            "type": "string",
            "enum": ["owner", "admin", "analyst", "billing", "viewer"],
            "default": "analyst"
          }
        }
      },
      "OrgProfilePatchRequest": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "example": "Acme Bank Security Operations" },
          "billing_email": { "type": "string", "format": "email", "example": "finops@acmebank.com" }
        }
      },
      "BillingCheckoutRequest": {
        "type": "object",
        "required": ["action"],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "pro",
              "team",
              "regulated",
              "pack_1000",
              "takedown_199",
              "billing_portal",
              "downgrade_free"
            ],
            "example": "pro"
          },
          "billing": {
            "type": "string",
            "enum": ["monthly", "annual"],
            "default": "monthly"
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/scan": {
      "get": {
        "tags": ["Scans"],
        "summary": "List recent public community scans",
        "description": "Returns up to 50 recent public scan verdicts from Cloudflare D1 (`scan_verdicts`). Private organization scans are strictly excluded.",
        "security": [],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent public community scan feed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "max_history_limit": { "type": "integer", "example": 50 },
                    "scans": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ScanVerdictSummary" }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Scans"],
        "summary": "Submit URL or SMS scam lure for analysis",
        "description": "Two-tier Cloudflare execution gateway. Checks 15-minute Edge cache (0 credits on cache hit), deducts credits atomically in D1 (`fast`=1, `stealth`=3, `deep_recon`=10), and returns or enqueues the 10-category threat verdict.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ScanRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Synchronous verdict or cached scan document returned",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ScanVerdictSummary" }
              }
            }
          },
          "202": {
            "description": "Enqueued to Cloudflare Container Sandbox (`stealth` / `deep_recon`)"
          },
          "400": {
            "description": "Missing URL or SSRF/private target blocked",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          },
          "401": { "description": "Authentication required for private scans or invalid API key" },
          "402": { "description": "Insufficient scan credits or paid plan required" },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    },
    "/api/v1/scan/{id}": {
      "get": {
        "tags": ["Scans"],
        "summary": "Fetch complete or profile-sliced scan verdict",
        "parameters": [
          { "$ref": "#/components/parameters/SubmissionIdParam" },
          {
            "name": "profile",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "full",
                "dashboard_security",
                "dashboard_basic",
                "api_threat_intel",
                "minimal",
                "core",
                "threat",
                "dom",
                "network"
              ],
              "default": "full"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": { "type": "string", "enum": ["json", "csv"], "default": "json" }
          }
        ],
        "responses": {
          "200": { "description": "ScanDocumentV3 verdict payload (or CSV row when format=csv)" },
          "403": { "description": "Private scan belongs to another organization" },
          "404": { "description": "Scan submission not found" }
        }
      }
    },
    "/api/v1/scan/{id}/executive": {
      "get": {
        "tags": ["Scans"],
        "summary": "Export Executive Board summary (HTML or JSON)",
        "parameters": [
          { "$ref": "#/components/parameters/SubmissionIdParam" },
          { "$ref": "#/components/parameters/FrameworkQueryParam" },
          { "$ref": "#/components/parameters/SectorQueryParam" },
          {
            "name": "format",
            "in": "query",
            "schema": { "type": "string", "enum": ["html", "json"], "default": "html" }
          }
        ],
        "responses": {
          "200": { "description": "Printable vector HTML or structured JSON executive digest" },
          "403": { "description": "Private scan requires owning organization authentication" },
          "404": { "description": "Scan not found" }
        }
      }
    },
    "/api/v1/scan/{id}/csv": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "Download RFC-4180 PII-scrubbed Multi-Signal IOC CSV",
        "parameters": [{ "$ref": "#/components/parameters/SubmissionIdParam" }],
        "responses": {
          "200": { "description": "text/csv IOC export protected against spreadsheet formula injection" },
          "404": { "description": "Scan not found" }
        }
      }
    },
    "/api/v1/scan/{id}/pdf": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "Render print-ready Ombudsman & Board PDF dossier",
        "parameters": [
          { "$ref": "#/components/parameters/SubmissionIdParam" },
          { "$ref": "#/components/parameters/FrameworkQueryParam" },
          { "$ref": "#/components/parameters/SectorQueryParam" }
        ],
        "responses": {
          "200": { "description": "Print-optimized Executive & Ombudsman compliance dossier" },
          "404": { "description": "Scan not found" }
        }
      }
    },
    "/api/v1/scan/{id}/stream": {
      "get": {
        "tags": ["Scans"],
        "summary": "Stream live SSE scan execution milestones",
        "parameters": [{ "$ref": "#/components/parameters/SubmissionIdParam" }],
        "responses": {
          "200": { "description": "text/event-stream Server-Sent Events feed" },
          "403": { "description": "Private scan belongs to another organization" }
        }
      }
    },
    "/api/v1/scan/{id}/artifacts/{type}": {
      "get": {
        "tags": ["Scans"],
        "summary": "Download forensic screenshot, HAR, DOM, scan document, or evidence bundle",
        "parameters": [
          { "$ref": "#/components/parameters/SubmissionIdParam" },
          {
            "name": "type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "screenshot",
                "har",
                "dom",
                "evidence_bundle",
                "scan_document"
              ]
            }
          }
        ],
        "responses": {
          "200": { "description": "Zero-egress Cloudflare R2 forensic artifact stream" },
          "402": { "description": "Paid plan required for raw forensic artifact downloads" },
          "403": { "description": "Private scan belongs to another organization" },
          "404": { "description": "Artifact not found" }
        }
      }
    },
    "/api/v1/scan/{id}/diff": {
      "get": {
        "tags": ["Scans"],
        "summary": "Compute architectural, visual, and DOM drift against baseline",
        "parameters": [
          { "$ref": "#/components/parameters/SubmissionIdParam" },
          {
            "name": "compare_to",
            "in": "query",
            "required": false,
            "description": "Optional baseline submission_id to diff against.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Infrastructure, risk score, and DOM drift report" },
          "404": { "description": "Scan not found" }
        }
      }
    },
    "/api/v1/scan/{id}/stix": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "Download OASIS STIX 2.1 Threat Intelligence Bundle",
        "parameters": [{ "$ref": "#/components/parameters/SubmissionIdParam" }],
        "responses": {
          "200": { "description": "application/stix+json;version=2.1 bundle" },
          "404": { "description": "Scan not found" }
        }
      },
      "post": {
        "tags": ["Compliance & TAXII"],
        "summary": "Push signed STIX 2.1 IOCs to SIEM/SOAR webhook",
        "parameters": [{ "$ref": "#/components/parameters/SubmissionIdParam" }],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "webhook_url": { "type": "string", "format": "uri" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "HMAC-SHA256 signed STIX 2.1 delivery receipt" },
          "401": { "description": "Authentication required" }
        }
      }
    },
    "/api/v1/scan/{id}/compliance": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "Build or fetch 6-regime statutory ASI dossier",
        "parameters": [
          { "$ref": "#/components/parameters/SubmissionIdParam" },
          { "$ref": "#/components/parameters/FrameworkQueryParam" },
          { "$ref": "#/components/parameters/SectorQueryParam" },
          {
            "name": "sharing_tier",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "TIER_0_INTERNAL_VAULT",
                "TIER_1_IOC_ONLY",
                "TIER_2_REDACTED_REGULATORY_ASI",
                "TIER_3_BILATERAL_UNREDACTED_FORENSIC"
              ]
            }
          },
          {
            "name": "download",
            "in": "query",
            "schema": { "type": "boolean" }
          }
        ],
        "responses": {
          "200": { "description": "Cryptographically signed ASI Safe-Harbor Dossier" },
          "404": { "description": "Scan not found" }
        }
      },
      "post": {
        "tags": ["Compliance & TAXII"],
        "summary": "Certify or dispatch statutory ASI dossier to SIEM / Regulator",
        "parameters": [{ "$ref": "#/components/parameters/SubmissionIdParam" }],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ComplianceDispatchRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Certified and dispatched via HMAC-SHA256 connector" },
          "202": { "description": "Queued for Maker-Checker Compliance Officer approval" },
          "401": { "description": "Authentication required" }
        }
      },
      "patch": {
        "tags": ["Compliance & TAXII"],
        "summary": "Append versioned lifecycle delta (v1 -> v2 -> vN) or inbound regulator ACK",
        "parameters": [{ "$ref": "#/components/parameters/SubmissionIdParam" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ComplianceLifecyclePatchRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated versioned ASI lifecycle ledger" },
          "401": { "description": "Bearer API key or X-SentrySurface-Signature-256 HMAC callback required" }
        }
      }
    },
    "/api/v1/scan/{id}/dispute-pack": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "Export unified Ombudsman & EDR Dispute Defense Pack",
        "description": "Combines PII-scrubbed ASI dossier, STIX 2.1 bundle, IOC CSV, Executive HTML digest, takedown SLA timeline, linked customer IDR complaints, and detached HMAC-SHA256 manifest signature (AFCA, UK FOS, SG FIDReC, US CFPB Reg E).",
        "parameters": [
          { "$ref": "#/components/parameters/SubmissionIdParam" },
          { "$ref": "#/components/parameters/FrameworkQueryParam" },
          { "$ref": "#/components/parameters/SectorQueryParam" },
          {
            "name": "complaint_id",
            "in": "query",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "download",
            "in": "query",
            "required": false,
            "schema": { "type": "boolean" }
          }
        ],
        "responses": {
          "200": { "description": "Signed Ombudsman Dispute Defense Pack JSON" },
          "402": { "description": "Paid plan required for downloadable signed packs" },
          "403": { "description": "Private scan belongs to another organization" },
          "404": { "description": "Scan not found" }
        }
      }
    },
    "/api/v1/workspace/overview": {
      "get": {
        "tags": ["Workspace"],
        "summary": "Fetch tenant-isolated Command Center KPIs, Action Items, and Maker-Checker queue",
        "responses": {
          "200": { "description": "Unified tenant Command Center overview payload" },
          "401": { "description": "Authentication required" }
        }
      },
      "post": {
        "tags": ["Workspace"],
        "summary": "Update Action Item state or stage/review Maker-Checker dual-control requests",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WorkspaceOverviewMutation" }
            }
          }
        },
        "responses": {
          "200": { "description": "Action item updated or Maker-Checker decision executed" },
          "201": { "description": "Maker-Checker dual-control request created" },
          "400": { "description": "Invalid action or missing required fields" },
          "401": { "description": "Authentication required" },
          "403": { "description": "RBAC role restriction or Two-Person Rule self-approval violation" }
        }
      }
    },
    "/api/v1/batches": {
      "get": {
        "tags": ["Intelligence"],
        "summary": "List recent bulk URL scan jobs for the organization",
        "responses": {
          "200": { "description": "Organization batch scan job history" },
          "401": { "description": "Invalid API key" }
        }
      },
      "post": {
        "tags": ["Intelligence"],
        "summary": "Submit up to 25 URLs or SMS lures for concurrent triage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BatchScanRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Batch execution summary and individual submission_ids" },
          "401": { "description": "Authentication required" },
          "402": { "description": "Pro, Team, or Regulated plan required for batch scanning" },
          "403": { "description": "Viewer/Billing read-only role cannot deduct scan credits" }
        }
      }
    },
    "/api/v1/brands": {
      "get": {
        "tags": ["Intelligence"],
        "summary": "List monitored brand kits, pHash references, and lookalike hits",
        "responses": {
          "200": { "description": "Organization brand watchlist" }
        }
      },
      "post": {
        "tags": ["Intelligence"],
        "summary": "Register brand kit for continuous typosquat & homoglyph watch",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BrandCreateRequest" }
            }
          }
        },
        "responses": {
          "201": { "description": "Brand kit registered with generated permutation watchlist" },
          "401": { "description": "Authentication required" },
          "402": { "description": "Plan brand watchlist limit reached" },
          "403": { "description": "Read-only role forbidden" }
        }
      },
      "patch": {
        "tags": ["Intelligence"],
        "summary": "Run live homograph sweep or update automated monitoring schedule",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BrandPatchRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Sweep completed (with auto-staged protection) or schedule updated" },
          "429": { "description": "Sweep rate limit exceeded (max 10/min)" }
        }
      },
      "delete": {
        "tags": ["Intelligence"],
        "summary": "Remove monitored brand kit from watchlist",
        "parameters": [
          {
            "name": "brand_id",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Brand kit removed" },
          "401": { "description": "Authentication required" },
          "403": { "description": "Read-only role forbidden" }
        }
      }
    },
    "/api/v1/query": {
      "post": {
        "tags": ["Intelligence"],
        "summary": "Tenant-isolated NL-to-SQL Lakehouse Threat Hunter",
        "description": "Executes strictly parameterized `WHERE org_id = ?` analytical queries across `scan_verdicts`, `customer_complaints`, `threat_ioc_index`, `takedown_cases`, `compliance_reports`, `brand_kits`, `compliance_delivery_ledger`, and `org_audit_logs`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/QueryRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Structured analytical rows and compiled SQL metadata" },
          "401": { "description": "Authentication required" }
        }
      }
    },
    "/api/v1/takedown": {
      "get": {
        "tags": ["Operations"],
        "summary": "List registrar & ASN takedown cases",
        "parameters": [
          {
            "name": "submission_id",
            "in": "query",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Organization takedown cases and defanging SLA telemetry" }
        }
      },
      "post": {
        "tags": ["Operations"],
        "summary": "Dispatch or stage registrar/ASN abuse takedown with RDAP vCard lookup",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TakedownRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Forensic evidence bundle compiled and takedown dispatched" },
          "202": { "description": "Staged for Maker-Checker dual-control approval" },
          "401": { "description": "Authentication required" },
          "403": { "description": "Read-only role forbidden" }
        }
      },
      "patch": {
        "tags": ["Operations"],
        "summary": "Advance takedown lifecycle status or trigger live DNS/HTTP defanging check",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TakedownPatchRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Takedown lifecycle updated (auto-syncs linked ASI & complaints on defanged)" },
          "401": { "description": "Authentication required" },
          "404": { "description": "Takedown case not found" }
        }
      }
    },
    "/api/v1/complaints": {
      "get": {
        "tags": ["Operations"],
        "summary": "List customer scam complaints, campaign clusters, and IDR SLA timers",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "triaging",
                "investigating",
                "stop_clock_paused",
                "pending_settlement_approval",
                "reimbursed",
                "partially_settled",
                "declined_safe_harbor",
                "defanged_resolved"
              ]
            }
          },
          { "name": "cluster", "in": "query", "schema": { "type": "string" } },
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "csv"] } }
        ],
        "responses": {
          "200": { "description": "Complaints queue, campaign clusters, or RFC-4180 IDR Register CSV" },
          "401": { "description": "Authentication required" }
        }
      },
      "post": {
        "tags": ["Operations"],
        "summary": "Log and triage customer scam complaint or APP/ATO dispute",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ComplaintCreateRequest" }
            }
          }
        },
        "responses": {
          "201": { "description": "Complaint logged, PII scrubbed, clustered, and IDR SLA calculated" },
          "401": { "description": "Authentication required" },
          "403": { "description": "Read-only role forbidden" }
        }
      },
      "patch": {
        "tags": ["Operations"],
        "summary": "Transition complaint or campaign cluster across IDR/EDR dispute states",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ComplaintPatchRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Complaint or campaign cluster lifecycle updated" },
          "403": { "description": "Maker-Checker settlement approval requires Owner/Admin" },
          "404": { "description": "Complaint or cluster not found" }
        }
      }
    },
    "/api/v1/complaints/config": {
      "get": {
        "tags": ["Operations"],
        "summary": "Get branded /report/{slug} intake & CRM Helpdesk webhook configuration",
        "responses": {
          "200": { "description": "Complaints portal config, CRM presets, and delivery ledger" },
          "401": { "description": "Authentication required" }
        }
      },
      "post": {
        "tags": ["Operations"],
        "summary": "Test CRM webhook ping, rotate CRM HMAC secret, or replay dead-letter delivery",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["action"],
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "test_crm_ping",
                      "rotate_hmac_secret",
                      "retry_crm_delivery"
                    ],
                    "example": "test_crm_ping"
                  },
                  "attempt_id": {
                    "type": "string",
                    "description": "Required when action is retry_crm_delivery."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "CRM action executed" },
          "403": { "description": "Owner/Admin required for ping/rotation; Analyst+ for retry" }
        }
      },
      "patch": {
        "tags": ["Operations"],
        "summary": "Update branded intake portal, official domains allowlist, & CRM webhook settings",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ComplaintConfigPatchRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated complaints & CRM configuration" },
          "403": { "description": "Organization Owner or Admin required" }
        }
      }
    },
    "/api/v1/complaints/inbound": {
      "post": {
        "tags": ["Operations"],
        "summary": "Bidirectional signed inbound CRM/Helpdesk webhook bridge",
        "description": "Accepts `ticket.created` and `ticket.status_updated` payloads from Zendesk, Salesforce Service Cloud, ServiceNow CSM, or Freshdesk. Verified via `X-SentrySurface-Timestamp` and `X-SentrySurface-Signature-256` (`sha256=<hmac_hex>`) within a 300s replay window.",
        "security": [],
        "parameters": [
          {
            "name": "org_slug",
            "in": "query",
            "required": false,
            "description": "Target organization portal slug (or pass X-SentrySurface-Org-Slug header).",
            "schema": { "type": "string" }
          },
          {
            "name": "X-SentrySurface-Timestamp",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "example": "1763420000" }
          },
          {
            "name": "X-SentrySurface-Signature-256",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "example": "sha256=0123456789abcdef..." }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "enum": ["ticket.created", "ticket.status_updated"],
                    "default": "ticket.created"
                  },
                  "external_ticket_ref": { "type": "string", "example": "ZD-49201" },
                  "complaint_id": { "type": "string" },
                  "status": { "type": "string" },
                  "suspect_url": { "type": "string", "format": "uri" },
                  "sms_body": { "type": "string" },
                  "claimed_loss_amount": { "type": "number" },
                  "claimed_loss_currency": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Ticket synchronized with IDR queue" },
          "201": { "description": "Inbound CRM ticket logged and triaged" },
          "401": { "description": "Invalid or expired HMAC-SHA256 signature" },
          "429": { "description": "Inbound webhook rate limit exceeded" }
        }
      }
    },
    "/api/v1/public-intake/{slug}": {
      "get": {
        "tags": ["Operations"],
        "summary": "Fetch public branded scam intake metadata or zero-PII case status",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "example": "acme-bank" }
          },
          {
            "name": "ref",
            "in": "query",
            "required": false,
            "description": "Optional CMP-YYYYMMDD-XXXXX case reference for zero-PII status lookup.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Public portal metadata or sanitized case status" },
          "404": { "description": "Portal disabled or reference code not found" },
          "429": { "description": "Public IP rate limit exceeded" }
        }
      },
      "post": {
        "tags": ["Operations"],
        "summary": "Submit consumer scam check or dispute via branded /report/{slug} portal",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "example": "acme-bank" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ComplaintCreateRequest" }
            }
          }
        },
        "responses": {
          "201": { "description": "Consumer report scrubbed, scanned, and routed to tenant IDR queue" },
          "404": { "description": "Public portal unavailable" },
          "429": { "description": "Public submission rate limit exceeded" }
        }
      }
    },
    "/api/v1/compliance/config": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "Get SIEM/SOAR & statutory regulator connector configuration",
        "responses": {
          "200": { "description": "Masked compliance config, delivery ledger, and preset catalog" }
        }
      },
      "post": {
        "tags": ["Compliance & TAXII"],
        "summary": "Execute signed SIEM/Regulator test ping, reveal/rotate HMAC secret, or retry delivery",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "test_ping",
                      "acknowledge_or_reveal_hmac",
                      "retry_delivery"
                    ],
                    "default": "test_ping"
                  },
                  "framework": { "$ref": "#/components/schemas/RegulatoryFramework" },
                  "endpoint_url": { "type": "string", "format": "uri" },
                  "attempt_id": { "type": "string" },
                  "force_rotate": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Signed connector ping, HMAC custody response, or delivery retry result" },
          "401": { "description": "Authentication required" },
          "403": { "description": "Owner/Admin required for ping/HMAC; Analyst+ for retry" }
        }
      },
      "patch": {
        "tags": ["Compliance & TAXII"],
        "summary": "Update SIEM/Regulator connector presets, TLP sharing tier, HMAC secret, or circuit breaker",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "default_framework": { "$ref": "#/components/schemas/RegulatoryFramework" },
                  "default_sector": { "$ref": "#/components/schemas/RegulatedSector" },
                  "connector_preset": {
                    "type": "string",
                    "enum": [
                      "vault_manual",
                      "splunk_hec",
                      "microsoft_sentinel",
                      "servicenow_secops",
                      "afcx_intel_loop",
                      "fs_isac_taxii",
                      "cifas_uk_finance",
                      "custom_regulator_gateway"
                    ]
                  },
                  "default_webhook_url": { "type": "string", "format": "uri" },
                  "auth_type": {
                    "type": "string",
                    "enum": [
                      "hmac_only",
                      "bearer_token",
                      "splunk_hec_token",
                      "custom_api_key"
                    ]
                  },
                  "approval_workflow": {
                    "type": "string",
                    "enum": ["auto_push_telemetry", "require_officer_approval"]
                  },
                  "default_sharing_tier": {
                    "type": "string",
                    "enum": [
                      "TIER_0_INTERNAL_VAULT",
                      "TIER_1_IOC_ONLY",
                      "TIER_2_REDACTED_REGULATORY_ASI",
                      "TIER_3_BILATERAL_UNREDACTED_FORENSIC"
                    ]
                  },
                  "default_tlp_marking": {
                    "type": "string",
                    "enum": [
                      "TLP:CLEAR",
                      "TLP:GREEN",
                      "TLP:AMBER",
                      "TLP:AMBER+STRICT"
                    ]
                  },
                  "rotate_hmac_secret": { "type": "boolean" },
                  "reset_circuit_breaker": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated compliance connector configuration" },
          "403": { "description": "Organization Owner or Admin required" }
        }
      }
    },
    "/api/v1/compliance/overview": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "Get dynamic tenant governance scorecard, IDR summary, and ASI delivery ledger",
        "responses": {
          "200": { "description": "Tenant compliance scorecard and persisted ASI dossiers" }
        }
      }
    },
    "/api/v1/onboarding/regulated": {
      "get": {
        "tags": ["Admin & Billing"],
        "summary": "Get 5-stage regulated workspace onboarding readiness assessment",
        "responses": {
          "200": { "description": "Regulated onboarding stage checklist and readiness percentage" },
          "401": { "description": "Authentication required" }
        }
      },
      "post": {
        "tags": ["Admin & Billing"],
        "summary": "Submit corporate licence/ABN/UEN/FRN/LEI or run statutory onboarding dry-run",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "step": {
                    "type": "string",
                    "enum": [
                      "entity_identity",
                      "governance_roles",
                      "connector_setup",
                      "portal_setup",
                      "statutory_dry_run"
                    ],
                    "example": "statutory_dry_run"
                  },
                  "legal_entity_name": { "type": "string" },
                  "entity_identifier_type": { "type": "string", "example": "AU_ABN" },
                  "entity_identifier_value": { "type": "string" },
                  "default_framework": { "$ref": "#/components/schemas/RegulatoryFramework" },
                  "default_sector": { "$ref": "#/components/schemas/RegulatedSector" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated onboarding readiness state and dry-run receipts" },
          "401": { "description": "Authentication required" },
          "403": { "description": "Owner/Admin required for org onboarding mutations" }
        }
      }
    },
    "/api/v1/taxii2/": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "OASIS TAXII 2.1 Server Discovery",
        "security": [],
        "responses": {
          "200": { "description": "application/taxii+json;version=2.1 discovery document" }
        }
      }
    },
    "/api/v1/taxii2/api-root": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "OASIS TAXII 2.1 API Root metadata",
        "responses": {
          "200": { "description": "Primary Threat Intelligence API Root metadata" },
          "401": { "description": "Invalid API key" }
        }
      }
    },
    "/api/v1/taxii2/api-root/collections": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "List OASIS TAXII 2.1 threat intelligence collections",
        "responses": {
          "200": {
            "description": "Collections catalog (col_phishing_iocs, col_regulatory_asi, col_brand_typosquats, col_cve_vulnerabilities, col_customer_reported_scams)"
          },
          "401": { "description": "Invalid API key" }
        }
      }
    },
    "/api/v1/taxii2/api-root/collections/{collectionId}/objects": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "Retrieve STIX 2.1 threat objects from a TAXII 2.1 collection",
        "parameters": [
          {
            "name": "collectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "col_phishing_iocs",
                "col_regulatory_asi",
                "col_brand_typosquats",
                "col_cve_vulnerabilities",
                "col_customer_reported_scams"
              ],
              "example": "col_phishing_iocs"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }
          }
        ],
        "responses": {
          "200": { "description": "OASIS TAXII 2.1 envelope containing STIX 2.1 objects" },
          "401": { "description": "Invalid API key" },
          "404": { "description": "Collection not found" }
        }
      }
    },
    "/api/v1/mcp": {
      "get": {
        "tags": ["MCP Server"],
        "summary": "Discover Streamable HTTP MCP Server capabilities & 11-tool schema catalog",
        "security": [],
        "responses": {
          "200": { "description": "MCP protocol metadata and 11 tool JSON schemas" }
        }
      },
      "post": {
        "tags": ["MCP Server"],
        "summary": "Execute JSON-RPC 2.0 Streamable HTTP MCP request (initialize, tools/list, tools/call)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/McpJsonRpcRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "JSON-RPC 2.0 response envelope (with prompt-injection spotlighting on untrusted strings)" },
          "401": { "description": "Invalid API key" }
        }
      }
    },
    "/api/v1/audit": {
      "get": {
        "tags": ["Compliance & TAXII"],
        "summary": "Query immutable organization SOC 2 & compliance audit log",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "scan",
                "batch",
                "brand",
                "takedown",
                "apikey",
                "compliance",
                "billing",
                "org",
                "security"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }
          },
          {
            "name": "format",
            "in": "query",
            "schema": { "type": "string", "enum": ["json", "csv"], "default": "json" }
          }
        ],
        "responses": {
          "200": { "description": "Immutable organization audit events (JSON or RFC-4180 CSV)" },
          "401": { "description": "Authentication required for CSV export or invalid API key" }
        }
      }
    },
    "/api/v1/org": {
      "get": {
        "tags": ["Admin & Billing"],
        "summary": "Get organization profile, plan seat usage, RBAC members, and billing events",
        "responses": {
          "200": { "description": "Organization profile and RBAC seat directory" }
        }
      },
      "post": {
        "tags": ["Admin & Billing"],
        "summary": "Invite team member or update existing member RBAC role",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/OrgMemberUpsertRequest" }
            }
          }
        },
        "responses": {
          "201": { "description": "Team member invited or role updated" },
          "402": { "description": "Plan seat limit reached" },
          "403": { "description": "Organization Owner or Admin required" }
        }
      },
      "patch": {
        "tags": ["Admin & Billing"],
        "summary": "Update organization display name and billing/compliance email",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/OrgProfilePatchRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Organization profile updated" },
          "403": { "description": "Organization Owner or Admin required" }
        }
      },
      "delete": {
        "tags": ["Admin & Billing"],
        "summary": "Remove or revoke an organization team member seat",
        "parameters": [
          {
            "name": "member_id",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Member seat revoked" },
          "403": { "description": "Organization Owner or Admin required" }
        }
      }
    },
    "/api/v1/keys": {
      "get": {
        "tags": ["Admin & Billing"],
        "summary": "List active workspace API keys (masked prefixes) and credit balance",
        "responses": {
          "200": { "description": "Workspace API key metadata and credit balance" }
        }
      },
      "post": {
        "tags": ["Admin & Billing"],
        "summary": "Mint a new SHA-256 hashed workspace API key",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" }
            }
          }
        },
        "responses": {
          "201": { "description": "New API key minted (raw `api_key` returned once)" },
          "401": { "description": "Authentication required" },
          "403": { "description": "Organization Owner or Admin required" }
        }
      },
      "delete": {
        "tags": ["Admin & Billing"],
        "summary": "Revoke an active workspace API key by key_prefix",
        "parameters": [
          {
            "name": "key_prefix",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "example": "sk_live_sentry_9a8b" }
          }
        ],
        "responses": {
          "200": { "description": "API key revoked immediately across Cloudflare Edge" },
          "401": { "description": "Authentication required" },
          "403": { "description": "Organization Owner or Admin required" }
        }
      }
    },
    "/api/v1/billing": {
      "get": {
        "tags": ["Admin & Billing"],
        "summary": "Get active subscription plan, pricing catalog, and credit balance",
        "responses": {
          "200": { "description": "Billing status and plan catalog" }
        }
      },
      "post": {
        "tags": ["Admin & Billing"],
        "summary": "Create Stripe Checkout session, open Customer Billing Portal, or process Stripe webhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BillingCheckoutRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Stripe Checkout URL, Billing Portal URL, or sandbox upgrade summary" },
          "401": { "description": "Authentication required" },
          "403": { "description": "Owner, Admin, or Billing Officer role required" }
        }
      }
    },
    "/api/v1/session": {
      "get": {
        "tags": ["Admin & Billing"],
        "summary": "Get active session identity, plan allowance, RBAC role, and corporate domain status",
        "security": [],
        "responses": {
          "200": { "description": "Workspace session summary" }
        }
      }
    }
  }
}
