{ "openapi": "3.1.0", "info": { "title": "USComplianceAPI External Integration API", "version": "1.0.0", "description": "Customer-facing integration contract. All documented endpoints are served by the published app's function routes at /functions/; the branded host api.uscomplianceapi.com is live and TLS-verified. The platform provides no custom path rewrites such as /v1/compliance-audit." }, "servers": [ { "url": "https://api.uscomplianceapi.com/functions", "description": "Live branded API host - the published app's function routes, TLS-verified." }, { "url": "https://swarm-nexus-ai.base44.app/functions", "description": "Default Base44 function host; the same routes serve every documented function." } ], "paths": { "/complianceAudit": { "post": { "operationId": "complianceAudit", "summary": "Audit supplied content with the active database rulebook", "description": "The customer API contract for POST https://api.uscomplianceapi.com/functions/complianceAudit. Live and TLS-verified: the platform serves functions at /functions/ and provides no custom path rewrites such as /v1/compliance-audit.", "x-deployment-status": "live-verified", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceAuditRequest" }, "example": { "content": "Our retail chatbot says: Act now. Limited-time offer.", "jurisdiction": "ALL", "industry": "retail" } } } }, "responses": { "200": { "description": "Audit completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceAuditResponse" } } } }, "400": { "$ref": "#/components/responses/PublicInvalidRequest" }, "401": { "$ref": "#/components/responses/PublicInvalidApiKey" }, "402": { "$ref": "#/components/responses/PublicInactiveAccount" }, "429": { "$ref": "#/components/responses/PublicRateOrQuotaExceeded" }, "503": { "$ref": "#/components/responses/PublicServiceUnavailable" } } } }, "/agentSubscribe": { "post": { "operationId": "accountOperations", "summary": "Verify an API-key account, retrieve activity, or export activity CSV", "description": "Base44 function endpoint: POST /agentSubscribe. All documented API-key actions authenticate against the canonical Supabase client-account/key/activity store; no Base44 account mirror is required. External integrations should use X-API-Key; the optional api_key request body field is retained only for existing Client Dashboard compatibility.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyVerifyRequest" }, { "$ref": "#/components/schemas/ApiKeyLogsRequest" }, { "$ref": "#/components/schemas/ApiKeyExportRequest" } ], "discriminator": { "propertyName": "action", "mapping": { "verify": "#/components/schemas/ApiKeyVerifyRequest", "get_logs": "#/components/schemas/ApiKeyLogsRequest", "export_audit": "#/components/schemas/ApiKeyExportRequest" } } } } } }, "responses": { "200": { "description": "Verification/activity JSON or CSV export, selected by action.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyVerificationResponse" }, { "$ref": "#/components/schemas/ApiKeyActivityLogResponse" } ] } }, "text/csv": { "schema": { "type": "string", "description": "timestamp,endpoint_queried,status_code,response_latency_ms,plan,is_agent rows for export_audit." } } } }, "400": { "$ref": "#/components/responses/ApiKeyOperationBadRequest" }, "401": { "$ref": "#/components/responses/ApiKeyOperationUnauthorized" }, "402": { "$ref": "#/components/responses/ApiKeyOperationInactive" }, "429": { "$ref": "#/components/responses/ApiKeyOperationRateLimited" }, "500": { "$ref": "#/components/responses/ApiKeyOperationFailure" } }, "servers": [ { "url": "https://api.uscomplianceapi.com/functions" } ] } }, "/runWebsiteAudit": { "post": { "operationId": "runWebsiteAudit", "summary": "Run an anonymous, IP-limited website scan", "description": "Base44 function endpoint: POST /runWebsiteAudit. No authentication is required. Anonymous callers are limited to 10 requests/minute per runtime-observed IP; no authenticated account quota is applied to anonymous scans.", "security": [], "responses": { "200": { "description": "Website scan result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteAuditResponse" } } } }, "400": { "$ref": "#/components/responses/WebsiteError" }, "403": { "$ref": "#/components/responses/WebsiteError" }, "415": { "$ref": "#/components/responses/WebsiteError" }, "429": { "$ref": "#/components/responses/WebsiteError" }, "502": { "$ref": "#/components/responses/WebsiteError" }, "500": { "$ref": "#/components/responses/WebsiteError" } }, "servers": [ { "url": "https://api.uscomplianceapi.com/functions" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteAuditRequest" } } } } } }, "/webhookIngest": { "post": { "operationId": "ingestTranscriptWebhook", "summary": "Ingest an external conversation transcript", "description": "Base44 function endpoint: POST /webhookIngest. For ManyChat, HubSpot, Meta, CRMs, Zapier, Make, and n8n. It requires the deployment-issued x-webhook-secret header; X-API-Key and body secrets are rejected. Redact unnecessary sensitive data before submission because transcript payloads are persisted for audit/reporting.", "security": [ { "WebhookSecretAuth": [] } ], "responses": { "200": { "description": "Successful evaluation and persistence acknowledgement. Authentication and documented payload validation errors return 401/400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookIngestResponse" } } } }, "400": { "$ref": "#/components/responses/WebhookError" }, "401": { "$ref": "#/components/responses/WebhookError" }, "500": { "$ref": "#/components/responses/WebhookError" }, "503": { "$ref": "#/components/responses/WebhookError" } }, "servers": [ { "url": "https://api.uscomplianceapi.com/functions" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTranscriptRequest" } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "WebhookSecretAuth": { "type": "apiKey", "in": "header", "name": "x-webhook-secret", "description": "Deployment-issued integration secret. Send it only in this header; never send it as X-API-Key or in the JSON body." } }, "schemas": { "ComplianceAuditRequest": { "type": "object", "additionalProperties": false, "required": [ "content", "jurisdiction" ], "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 30000, "description": "Text, HTML, script, or asset description to audit." }, "jurisdiction": { "type": "string", "enum": [ "TN", "CA", "TX", "CO", "NY", "FL", "MA", "AZ", "UT", "OR", "ALL" ] }, "industry": { "type": "string", "enum": [ "healthcare", "fintech", "media", "hr", "retail", "legaltech" ] }, "asset_url": { "type": "string", "format": "uri", "description": "Optional http(s) evidence context. The endpoint does not fetch it.", "pattern": "^https?://[^/\\s]+" } } }, "ComplianceAuditResponse": { "type": "object", "required": [ "verdict", "risk_score", "statutes", "penalty_exposure_usd", "remediation", "jurisdiction", "usage" ], "properties": { "verdict": { "type": "string", "enum": [ "GREEN", "YELLOW", "RED" ] }, "risk_score": { "type": "number", "minimum": 0, "maximum": 100 }, "statutes": { "type": "array", "items": { "$ref": "#/components/schemas/Statute" } }, "penalty_exposure_usd": { "type": "number", "minimum": 0 }, "remediation": { "type": "array", "items": { "$ref": "#/components/schemas/Remediation" } }, "jurisdiction": { "type": "string" }, "industry": { "type": "string" }, "usage": { "type": "object", "required": [ "count", "monthly_limit" ], "properties": { "count": { "type": "integer" }, "monthly_limit": { "type": [ "integer", "null" ] } } } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Statute": { "type": "object", "required": [ "tier_key", "citation", "penalty_usd" ], "properties": { "tier_key": { "type": "string" }, "citation": { "type": "string" }, "penalty_usd": { "type": "number", "minimum": 0 } } }, "Remediation": { "type": "object", "required": [ "rule_key", "title", "recommendation" ], "properties": { "rule_key": { "type": "string" }, "title": { "type": "string" }, "recommendation": { "type": "string" } } }, "WebsiteAuditRequest": { "type": "object", "additionalProperties": false, "required": [ "target_url" ], "properties": { "target_url": { "type": "string", "format": "uri", "pattern": "^https?://[^/\\s]+" } } }, "Finding": { "type": "object", "required": [ "title", "plain_english", "category", "evidence" ], "properties": { "rule_key": { "type": "string" }, "title": { "type": "string" }, "plain_english": { "type": "string" }, "category": { "type": "string" }, "statute_ref": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "required": [ "type", "excerpt", "source_url" ], "properties": { "type": { "type": "string" }, "excerpt": { "type": "string" }, "source_url": { "type": "string" } } } } } }, "WebsiteAuditResponse": { "type": "object", "required": [ "score", "grade", "critical", "warnings", "passed", "scan_meta" ], "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "grade": { "type": "string" }, "critical": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } }, "passed": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } }, "scan_meta": { "type": "object", "required": [ "fetched", "status_code", "robots_respected", "scan_duration_ms", "engine_version", "rulebook_source" ], "properties": { "fetched": { "type": "boolean" }, "status_code": { "type": "integer" }, "robots_respected": { "type": "boolean" }, "scan_duration_ms": { "type": "number" }, "engine_version": { "type": "string" }, "rulebook_source": { "const": "database", "description": "The validated rulebook source used for this scan." } } } } }, "WebhookMessage": { "type": "object", "additionalProperties": false, "required": [ "sender", "text" ], "properties": { "sender": { "type": "string", "enum": [ "bot", "user" ] }, "text": { "type": "string", "minLength": 1 }, "timestamp": { "type": "string", "format": "date-time" } } }, "WebhookTranscriptRequest": { "type": "object", "additionalProperties": false, "required": [ "source", "messages" ], "properties": { "source": { "type": "string", "minLength": 1 }, "channel": { "type": "string" }, "account_id": { "type": "string" }, "conversation_id": { "type": "string" }, "messages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookMessage" } } } }, "WebhookIngestResponse": { "oneOf": [ { "type": "object", "required": [ "success", "scan_result_id", "channel_origin", "grade", "score", "critical_violations", "warnings", "passed_checks", "processing_ms", "scan_meta" ], "properties": { "success": { "const": true }, "scan_result_id": { "type": "string" }, "channel_origin": { "type": "string" }, "external_conversation_id": { "type": "string" }, "grade": { "type": "string" }, "score": { "type": "number" }, "critical_violations": { "type": "integer" }, "warnings": { "type": "integer" }, "passed_checks": { "type": "integer" }, "processing_ms": { "type": "number" }, "scan_meta": { "type": "object", "required": ["rulebook_source"], "properties": { "rulebook_source": { "const": "database", "description": "The validated rulebook source used for this evaluation." } } } } }, { "type": "object", "required": [ "success", "error", "processing_ms" ], "properties": { "success": { "const": false }, "error": { "type": "string" }, "processing_ms": { "type": "number" } } } ] }, "ApiKeyVerifyRequest": { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "const": "verify" }, "api_key": { "type": "string", "minLength": 1, "description": "Compatibility field for the existing Client Dashboard Base44 invocation. External integrations should send X-API-Key instead." } } }, "ApiKeyLogsRequest": { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "const": "get_logs" }, "api_key": { "type": "string", "minLength": 1, "description": "Compatibility field for the existing Client Dashboard Base44 invocation. External integrations should send X-API-Key instead." } } }, "ApiKeyExportRequest": { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "const": "export_audit" }, "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "api_key": { "type": "string", "minLength": 1, "description": "Compatibility field for the existing Client Dashboard Base44 invocation. External integrations should send X-API-Key instead." } } }, "ApiKeyVerificationResponse": { "type": "object", "additionalProperties": false, "required": [ "valid", "plan", "billing_interval", "price_per_month_usd", "status", "usage_count", "trial_end" ], "properties": { "valid": { "const": true }, "plan": { "type": "string", "enum": [ "starter", "pro", "enterprise" ] }, "billing_interval": { "const": "month" }, "price_per_month_usd": { "type": [ "number", "null" ] }, "status": { "enum": [ "active", "trialing" ] }, "usage_count": { "type": "integer", "minimum": 0 }, "trial_end": { "type": [ "string", "null" ], "format": "date-time" } } }, "ApiKeyActivity": { "type": "object", "additionalProperties": false, "required": [ "timestamp", "endpoint_queried", "status_code", "response_latency_ms", "plan", "is_agent" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "endpoint_queried": { "type": "string" }, "status_code": { "type": "integer" }, "response_latency_ms": { "type": [ "number", "null" ] }, "plan": { "type": "string", "enum": [ "starter", "pro", "enterprise" ] }, "is_agent": { "type": "boolean" } } }, "ApiKeyActivityLogResponse": { "type": "object", "additionalProperties": false, "required": [ "logs", "account_id" ], "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyActivity" } }, "account_id": { "type": "string", "format": "uuid" } } }, "ApiKeyOperationErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "WebsiteErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "quota": { "type": "object", "properties": { "plan": { "type": "string" }, "used": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "WebhookErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "const": false }, "error": { "type": "string" }, "processing_ms": { "type": "number" } } } }, "responses": { "InvalidRequest": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InvalidApiKey": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InactiveAccount": { "description": "Account is not active or trialing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateOrQuotaExceeded": { "description": "Rate or monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "WebhookUnauthorized": { "description": "Missing or invalid webhook secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServiceUnavailable": { "description": "Active database rulebook unavailable or service failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ForbiddenTarget": { "description": "The target is disallowed by robots or security policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnsupportedTarget": { "description": "The target content type is unsupported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnreachableTarget": { "description": "The target could not be scanned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PublicInvalidRequest": { "description": "Malformed public compliance-audit request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PublicInvalidApiKey": { "description": "Missing or invalid public API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PublicInactiveAccount": { "description": "Public API account is not active or trialing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PublicRateOrQuotaExceeded": { "description": "Public API rate or monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PublicServiceUnavailable": { "description": "Active database rulebook unavailable or public API failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ApiKeyOperationBadRequest": { "description": "Malformed account operation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyOperationErrorResponse" } } } }, "ApiKeyOperationUnauthorized": { "description": "Missing or invalid account-operation API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyOperationErrorResponse" } } } }, "ApiKeyOperationInactive": { "description": "Account is not active or trialing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyOperationErrorResponse" } } } }, "ApiKeyOperationFailure": { "description": "Canonical account operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyOperationErrorResponse" } } } }, "WebsiteError": { "description": "Website scan error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteErrorResponse" } } } }, "WebhookError": { "description": "Sanitized webhook ingest authentication, payload-validation, evaluation-unavailable, or processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "ApiKeyOperationRateLimited": { "description": "verify exceeded its runtime-observed IP limit of 30 requests per minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyOperationErrorResponse" } } } } } } }