{ "openapi": "3.1.0", "info": { "title": "Fromenance API", "version": "1.0.0", "description": "Communication provenance for banks, credit unions, insurers, and utilities. Register every outbound communication at send time; verify what customers forward or paste. Errors are RFC 9457 problem details. All timestamps are UTC ISO 8601. Cursor pagination with `cursor` and `limit`.", "contact": { "name": "Fromenance", "url": "https://docs.fromenance.com", "email": "support@fromenance.com" }, "termsOfService": "https://fromenance.com/terms" }, "servers": [ { "url": "https://api.fromenance.com", "description": "Production" } ], "tags": [ { "name": "System" }, { "name": "Communications", "description": "Registration of sent communications." }, { "name": "Public", "description": "Web verify endpoints authenticated by site key." }, { "name": "Submissions" }, { "name": "Indicators" }, { "name": "Fraud list" }, { "name": "Domains" }, { "name": "Sending sources" }, { "name": "Reply templates" }, { "name": "Webhook endpoints" }, { "name": "Stats" }, { "name": "Tenant" }, { "name": "Hooks", "description": "Inbound webhooks from Resend and ESPs." } ], "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "description": "Tenant API key with fr_live_ or fr_test_ prefix." }, "SiteKey": { "type": "apiKey", "in": "header", "name": "X-Site-Key", "description": "Public site key for the verify widget. Bound to allowed origins." }, "Session": { "type": "apiKey", "in": "cookie", "name": "fromenance.session_token", "description": "Admin app or backoffice session." } }, "schemas": { "Health": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "version": { "type": "string" }, "environment": { "type": "string" }, "checks": { "type": "object", "properties": { "neon": { "type": "string", "enum": [ "ok", "error", "skipped" ] }, "d1": { "type": "string", "enum": [ "ok", "error" ] } }, "required": [ "neon", "d1" ] }, "time": { "type": "string" } }, "required": [ "status", "version", "environment", "checks", "time" ] }, "Me": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "name" ] }, "platform": { "type": "boolean" }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "membership_id": { "type": "string" }, "tenant_id": { "type": "string" }, "tenant_slug": { "type": "string" }, "tenant_name": { "type": "string" }, "role": { "type": "string" } }, "required": [ "membership_id", "tenant_id", "tenant_slug", "tenant_name", "role" ] } } }, "required": [ "user", "platform", "memberships" ] }, "Tenant": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": "string" }, "status": { "type": "string" }, "authoritative_mode": { "type": "boolean" }, "authoritative_since": { "type": [ "string", "null" ] }, "retention_days": { "type": "integer" }, "reply_mode": { "anyOf": [ { "type": "string", "enum": [ "minimal", "branded" ] }, { "type": "string" } ] }, "reply_from_name": { "type": [ "string", "null" ] }, "reply_domain_id": { "type": [ "string", "null" ] }, "fraud_contact": { "type": [ "string", "null" ] }, "verify_page_url": { "type": [ "string", "null" ] }, "verify_address": { "type": "string" }, "journal_address": { "type": "string" }, "minimal_reply_address": { "type": "string" }, "branding": { "type": "object", "additionalProperties": {} }, "match_threshold": { "type": "integer" }, "sandbox": { "type": "boolean" }, "expected_daily_volume": { "type": [ "integer", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "slug", "name", "plan", "status", "authoritative_mode", "authoritative_since", "retention_days", "reply_mode", "reply_from_name", "reply_domain_id", "fraud_contact", "verify_page_url", "verify_address", "journal_address", "minimal_reply_address", "branding", "match_threshold", "sandbox", "expected_daily_volume", "created_at" ] }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "example": "https://docs.fromenance.com/api/errors#validation" }, "title": { "type": "string", "example": "Validation failed" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "recipient_hash must start with hmac-sha256:" }, "instance": { "type": "string", "example": "/v1/communications" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] }, "description": "Present on validation problems." }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status" ] }, "TenantPatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "reply_mode": { "type": "string", "enum": [ "minimal", "branded" ] }, "reply_from_name": { "type": "string", "maxLength": 120 }, "reply_domain_id": { "type": [ "string", "null" ] }, "fraud_contact": { "type": "string", "maxLength": 200 }, "verify_page_url": { "type": "string", "maxLength": 300, "format": "uri" }, "branding": { "type": "object", "properties": { "logoUrl": { "type": "string", "format": "uri" }, "accent": { "type": "string", "maxLength": 20 }, "displayName": { "type": "string", "maxLength": 120 }, "supportUrl": { "type": "string", "format": "uri" } } }, "match_threshold": { "type": "integer", "minimum": 0, "maximum": 20 }, "retention_days": { "type": "integer", "minimum": 7, "maximum": 730 }, "expected_daily_volume": { "type": [ "integer", "null" ], "minimum": 0 } } }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "analyst", "integrator", "viewer" ] }, "status": { "type": "string" }, "invited_at": { "type": [ "string", "null" ] }, "accepted_at": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "email", "name", "role", "status", "invited_at", "accepted_at", "last_seen_at", "created_at" ] }, "InviteUser": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email" }, "role": { "type": "string", "enum": [ "owner", "admin", "analyst", "integrator", "viewer" ] }, "name": { "type": "string", "maxLength": 120 } }, "required": [ "email" ] }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "register", "read", "admin" ] } }, "last_used_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "prefix", "mode", "scopes", "last_used_at", "revoked_at", "created_at" ] }, "CreateApiKey": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "register", "read", "admin" ] }, "minItems": 1 } }, "required": [ "name" ] }, "AuditEntry": { "type": "object", "properties": { "id": { "type": "string" }, "actor_id": { "type": [ "string", "null" ] }, "actor_email": { "type": [ "string", "null" ] }, "actor_kind": { "type": "string" }, "action": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "target_id": { "type": [ "string", "null" ] }, "before": {}, "after": {}, "impersonating": { "type": "boolean" }, "at": { "type": "string" } }, "required": [ "id", "actor_id", "actor_email", "actor_kind", "action", "target", "target_id", "impersonating", "at" ] }, "Domain": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "pending", "verified", "suspended" ] }, { "type": "string" } ] }, "roles": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "trust", "sender", "reply" ] }, { "type": "string" } ] } }, "txt_record": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "TXT" ] }, "value": { "type": "string" } }, "required": [ "name", "type", "value" ] }, "verified_at": { "type": [ "string", "null" ] }, "last_checked_at": { "type": [ "string", "null" ] }, "last_check_result": { "type": [ "string", "null" ] }, "reply_identity": { "type": [ "object", "null" ], "properties": { "resend_domain_id": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": "number" }, "status": { "type": "string" } }, "required": [ "record", "name", "type", "value" ] } } }, "required": [ "resend_domain_id", "status", "records" ] }, "created_at": { "type": "string" } }, "required": [ "id", "domain", "status", "roles", "txt_record", "verified_at", "last_checked_at", "last_check_result", "reply_identity", "created_at" ] }, "AddDomain": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 3, "maxLength": 253, "example": "northfieldbank.com" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "trust", "sender", "reply" ] } } }, "required": [ "domain" ] }, "DomainPatch": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "string", "enum": [ "trust", "sender", "reply" ] }, "minItems": 1 } }, "required": [ "roles" ] }, "RegistrationResponse": { "type": "object", "properties": { "id": { "type": "string" }, "verify_code": { "type": "string", "example": "KX73-PQ9G" }, "expires_at": { "type": "string" }, "sandbox": { "type": "boolean" } }, "required": [ "id", "verify_code", "expires_at", "sandbox" ] }, "RegistrationRequest": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email" ] }, "recipient_hash": { "type": "string", "pattern": "^hmac-sha256:[0-9a-f]{64}$", "description": "HMAC-SHA256 of the lowercased, trimmed recipient address keyed with your tenant secret." }, "message_id": { "type": "string", "minLength": 1, "maxLength": 998 }, "from_address": { "type": "string", "minLength": 3, "maxLength": 320 }, "sent_at": { "type": "string", "format": "date-time" }, "subject_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "content_fingerprint": { "$ref": "#/components/schemas/ContentFingerprint" }, "link_domains": { "type": "array", "items": { "type": "string", "maxLength": 253 }, "maxItems": 50 }, "template_id": { "type": [ "string", "null" ], "maxLength": 120 }, "campaign_id": { "type": [ "string", "null" ], "maxLength": 120 }, "provider": { "type": "string", "enum": [ "api", "sendgrid", "ses", "resend", "postmark", "mailgun", "sfmc", "braze", "relay", "journal", "generic" ] }, "expires_at": { "type": "string", "format": "date-time" }, "verify_code": { "type": "string", "maxLength": 9, "description": "Only when completing a reserved code; otherwise omit and one is issued." } }, "required": [ "recipient_hash", "message_id", "from_address", "sent_at" ] }, "ContentFingerprint": { "type": "object", "properties": { "simhash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,16}$", "example": "0x9a4d3c2b1f0e8d7c" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "simhash", "sha256" ] }, "ReserveRequest": { "type": "object", "properties": { "recipient_hash": { "type": "string", "pattern": "^hmac-sha256:[0-9a-f]{64}$" }, "template_id": { "type": [ "string", "null" ], "maxLength": 120 }, "campaign_id": { "type": [ "string", "null" ], "maxLength": 120 }, "provider": { "type": "string", "enum": [ "api", "sendgrid", "ses", "resend", "postmark", "mailgun", "sfmc", "braze", "relay", "journal", "generic" ] }, "from_address": { "type": "string", "maxLength": 320 }, "expires_in_hours": { "type": "integer", "minimum": 1, "maximum": 72 } } }, "Communication": { "type": "object", "properties": { "id": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "recipient_hash": { "type": [ "string", "null" ] }, "message_id": { "type": [ "string", "null" ] }, "from_address": { "type": [ "string", "null" ] }, "sent_at": { "type": [ "string", "null" ] }, "verify_code": { "type": "string" }, "subject_fingerprint": { "type": [ "string", "null" ] }, "content_fingerprint": { "allOf": [ { "$ref": "#/components/schemas/ContentFingerprint" }, { "type": [ "object", "null" ] } ] }, "link_domains": { "type": "array", "items": { "type": "string" } }, "template_id": { "type": [ "string", "null" ] }, "campaign_id": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "source_id": { "type": [ "string", "null" ] }, "retro": { "type": "boolean" }, "sandbox": { "type": "boolean" }, "reserved_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "created_at": { "type": "string" }, "verifications": { "type": "array", "items": { "type": "object", "properties": { "submission_id": { "type": "string" }, "outcome": { "type": "string" }, "rule": { "type": "string" }, "received_at": { "type": "string" } }, "required": [ "submission_id", "outcome", "rule", "received_at" ] } } }, "required": [ "id", "channel", "status", "recipient_hash", "message_id", "from_address", "sent_at", "verify_code", "subject_fingerprint", "content_fingerprint", "link_domains", "template_id", "campaign_id", "provider", "source_id", "retro", "sandbox", "reserved_at", "completed_at", "expires_at", "created_at" ] }, "CompleteRequest": { "type": "object", "properties": { "recipient_hash": { "type": "string", "pattern": "^hmac-sha256:[0-9a-f]{64}$" }, "message_id": { "type": "string", "minLength": 1, "maxLength": 998 }, "from_address": { "type": "string", "minLength": 3, "maxLength": 320 }, "sent_at": { "type": "string", "format": "date-time" }, "subject_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "content_fingerprint": { "$ref": "#/components/schemas/ContentFingerprint" }, "link_domains": { "type": "array", "items": { "type": "string", "maxLength": 253 }, "maxItems": 50 }, "template_id": { "type": [ "string", "null" ], "maxLength": 120 }, "campaign_id": { "type": [ "string", "null" ], "maxLength": 120 }, "expires_at": { "type": "string", "format": "date-time" } } }, "Submission": { "type": "object", "properties": { "id": { "type": "string" }, "entry": { "type": "string" }, "status": { "type": "string" }, "received_at": { "type": "string" }, "processed_at": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "verify_code_found": { "type": [ "string", "null" ] }, "submitter_hash": { "type": [ "string", "null" ] }, "recipient_hash_found": { "type": [ "string", "null" ] }, "headers_present": { "type": "boolean" }, "dkim": { "type": [ "string", "null" ] }, "arc": { "type": [ "string", "null" ] }, "trust": { "type": [ "string", "null" ] }, "from_domain": { "type": [ "string", "null" ] }, "imitated_template_id": { "type": [ "string", "null" ] }, "campaign_id": { "type": [ "string", "null" ] }, "sandbox": { "type": "boolean" }, "verdict": { "$ref": "#/components/schemas/Verdict" }, "override": { "type": [ "object", "null" ], "properties": { "outcome": { "type": "string" }, "by": { "type": [ "string", "null" ] }, "at": { "type": "string" }, "note": { "type": [ "string", "null" ] } }, "required": [ "outcome", "by", "at", "note" ] } }, "required": [ "id", "entry", "status", "received_at", "processed_at", "count", "verify_code_found", "submitter_hash", "recipient_hash_found", "headers_present", "dkim", "arc", "trust", "from_domain", "imitated_template_id", "campaign_id", "sandbox", "verdict", "override" ] }, "Verdict": { "type": [ "object", "null" ], "properties": { "submission_id": { "type": "string" }, "outcome": { "type": "string", "enum": [ "verified", "not_verified", "known_fraud" ] }, "rule": { "type": "string" }, "replay": { "type": "boolean" }, "authoritative": { "type": "boolean" }, "matched": { "type": [ "object", "null" ], "properties": { "communication_id": { "type": "string" }, "sent_at": { "type": [ "string", "null" ] }, "template_id": { "type": [ "string", "null" ] } }, "required": [ "communication_id", "sent_at", "template_id" ] }, "signals": { "type": "object", "additionalProperties": {} }, "indicators": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "value": { "type": "string" } }, "required": [ "kind", "value" ] } }, "replied_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "submission_id", "outcome", "rule", "replay", "authoritative", "matched", "signals", "indicators", "replied_at", "created_at" ] }, "SubmissionDetail": { "allOf": [ { "$ref": "#/components/schemas/Submission" }, { "type": "object", "properties": { "subject": { "type": [ "string", "null" ] }, "preview_text": { "type": [ "string", "null" ], "description": "Plain text of the forwarded message with every link replaced by its bare domain." }, "headers_summary": { "type": "object", "properties": { "received": { "type": "array", "items": { "type": "string" } }, "dkim": { "type": [ "string", "null" ] }, "arc": { "type": [ "string", "null" ] }, "spf": { "type": [ "string", "null" ] }, "trust": { "type": [ "string", "null" ] } }, "required": [ "received", "dkim", "arc", "spf", "trust" ] }, "indicators": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "value": { "type": "string" }, "on_fraud_list": { "type": "boolean" }, "submission_count": { "type": "integer" } }, "required": [ "id", "kind", "value", "on_fraud_list", "submission_count" ] } }, "raw_available": { "type": "boolean" } }, "required": [ "subject", "preview_text", "headers_summary", "indicators", "raw_available" ] } ] }, "ReplyTemplate": { "type": "object", "properties": { "outcome": { "type": "string" }, "subject": { "type": "string" }, "body_mjml": { "type": "string" }, "locked_block_version": { "type": "integer" }, "locked_block_text": { "type": "string" }, "updated_at": { "type": "string" }, "is_default": { "type": "boolean" } }, "required": [ "outcome", "subject", "body_mjml", "locked_block_version", "locked_block_text", "updated_at", "is_default" ] }, "PublicVerdict": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "decided", "pending" ] }, "poll_token": { "type": [ "string", "null" ] }, "submission_id": { "type": "string" }, "outcome": { "type": [ "string", "null" ], "enum": [ "verified", "not_verified", "known_fraud", null ] }, "rule": { "type": [ "string", "null" ] }, "matched_sent_at": { "type": [ "string", "null" ] }, "signals": { "type": [ "object", "null" ], "properties": { "code_found": { "type": "boolean" }, "recipient_match": { "type": [ "boolean", "null" ] }, "fingerprint_distance": { "type": [ "number", "null" ] } }, "required": [ "code_found", "recipient_match", "fingerprint_distance" ] }, "display": { "type": [ "object", "null" ], "properties": { "institution_name": { "type": "string" }, "logo_url": { "type": [ "string", "null" ] }, "accent": { "type": [ "string", "null" ] }, "fraud_contact": { "type": [ "string", "null" ] }, "support_url": { "type": [ "string", "null" ] }, "outcome_label": { "type": "string" }, "verdict_text": { "type": "string" }, "next_step": { "type": "string" } }, "required": [ "institution_name", "logo_url", "accent", "fraud_contact", "support_url", "outcome_label", "verdict_text", "next_step" ] } }, "required": [ "status", "poll_token", "submission_id", "outcome", "rule", "matched_sent_at", "signals", "display" ] }, "PublicSubmit": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 200000, "description": "Pasted message text or HTML." }, "eml_base64": { "type": "string", "maxLength": 2000000, "description": "A .eml file, base64." }, "image_base64": { "type": "string", "maxLength": 8000000, "description": "A screenshot (PNG, JPEG, WebP), base64. Answered asynchronously." }, "code": { "type": "string", "maxLength": 12, "description": "Verify code typed by the customer." }, "email": { "type": "string", "format": "email", "description": "The customer's own address, hashed locally on our side and never stored in clear." }, "turnstile_token": { "type": "string", "maxLength": 4000 } } }, "SendingSource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "webhook_url": { "type": [ "string", "null" ] }, "needs_reserve": { "type": "boolean" }, "footer_merge_tag": { "type": [ "string", "null" ] }, "instructions": { "type": "array", "items": { "type": "string" } }, "expected_daily_volume": { "type": [ "integer", "null" ] }, "silence_alert_minutes": { "type": "integer" }, "health": { "type": "object", "properties": { "last_event_at": { "type": [ "string", "null" ] }, "events_last_hour": { "type": "integer" }, "signature_failures": { "type": "integer" }, "reserved": { "type": "integer" }, "completed": { "type": "integer" }, "reserve_to_complete_ratio": { "type": [ "number", "null" ] }, "coverage_gaps": { "type": "integer" }, "silent": { "type": "boolean" }, "registered_today": { "type": "integer" } }, "required": [ "last_event_at", "events_last_hour", "signature_failures", "reserved", "completed", "reserve_to_complete_ratio", "coverage_gaps", "silent", "registered_today" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "kind", "status", "webhook_url", "needs_reserve", "footer_merge_tag", "instructions", "expected_daily_volume", "silence_alert_minutes", "health", "created_at" ] }, "CreateSendingSource": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "kind": { "type": "string", "enum": [ "api", "journal", "resend", "sendgrid", "ses", "generic", "postmark", "mailgun", "sfmc", "braze" ] }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Adapter specific, encrypted at rest. For example api_key for Resend body retrieval or server_token for Postmark." }, "expected_daily_volume": { "type": [ "integer", "null" ], "minimum": 0 }, "silence_alert_minutes": { "type": "integer", "minimum": 5, "maximum": 20160 } }, "required": [ "name", "kind" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "last_delivery_at": { "type": [ "string", "null" ] }, "last_status": { "type": [ "integer", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "url", "events", "status", "description", "last_delivery_at", "last_status", "created_at" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint_id": { "type": "string" }, "event": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "last_status_code": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "replay_of": { "type": [ "string", "null" ] }, "payload": { "type": "object", "additionalProperties": {} }, "created_at": { "type": "string" } }, "required": [ "id", "endpoint_id", "event", "status", "attempts", "last_status_code", "last_error", "next_attempt_at", "delivered_at", "replay_of", "payload", "created_at" ] }, "Stats": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "integer" } }, "required": [ "from", "to", "days" ] }, "totals": { "type": "object", "properties": { "registered": { "type": "integer" }, "submitted": { "type": "integer" }, "verified": { "type": "integer" }, "not_verified": { "type": "integer" }, "known_fraud": { "type": "integer" }, "replays": { "type": "integer" }, "forwards": { "type": "integer" }, "web": { "type": "integer" }, "reply_p95_ms": { "type": [ "integer", "null" ] }, "reply_avg_ms": { "type": [ "integer", "null" ] }, "coverage_gaps": { "type": "integer" }, "code_found_rate": { "type": [ "number", "null" ] } }, "required": [ "registered", "submitted", "verified", "not_verified", "known_fraud", "replays", "forwards", "web", "reply_p95_ms", "reply_avg_ms", "coverage_gaps", "code_found_rate" ] }, "today": { "type": [ "object", "null" ], "properties": { "day": { "type": "string" }, "registered": { "type": "integer" }, "submitted": { "type": "integer" }, "verified": { "type": "integer" }, "not_verified": { "type": "integer" }, "known_fraud": { "type": "integer" }, "replays": { "type": "integer" }, "forwards": { "type": "integer" }, "web": { "type": "integer" }, "reply_p95_ms": { "type": [ "integer", "null" ] }, "by_source": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "day", "registered", "submitted", "verified", "not_verified", "known_fraud", "replays", "forwards", "web", "reply_p95_ms", "by_source" ] }, "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "registered": { "type": "integer" }, "submitted": { "type": "integer" }, "verified": { "type": "integer" }, "not_verified": { "type": "integer" }, "known_fraud": { "type": "integer" }, "replays": { "type": "integer" }, "forwards": { "type": "integer" }, "web": { "type": "integer" }, "reply_p95_ms": { "type": [ "integer", "null" ] }, "by_source": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "day", "registered", "submitted", "verified", "not_verified", "known_fraud", "replays", "forwards", "web", "reply_p95_ms", "by_source" ] } }, "coverage": { "type": "array", "items": { "type": "object", "properties": { "source_id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "registered": { "type": "integer" }, "expected": { "type": [ "integer", "null" ] }, "coverage": { "type": [ "number", "null" ] } }, "required": [ "source_id", "name", "kind", "registered", "expected", "coverage" ] } }, "top_indicators": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "value": { "type": "string" }, "submission_count": { "type": "integer" }, "last_seen": { "type": "string" }, "marked_fraud": { "type": "boolean" } }, "required": [ "kind", "value", "submission_count", "last_seen", "marked_fraud" ] } }, "authoritative_mode": { "type": "boolean" } }, "required": [ "range", "totals", "today", "days", "coverage", "top_indicators", "authoritative_mode" ] }, "Indicator": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "value": { "type": "string" }, "first_seen": { "type": "string" }, "last_seen": { "type": "string" }, "submission_count": { "type": "integer" }, "priority": { "type": "string" }, "on_fraud_list": { "type": "boolean" } }, "required": [ "id", "kind", "value", "first_seen", "last_seen", "submission_count", "priority", "on_fraud_list" ] }, "FraudListEntry": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" }, "added_by": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "submission_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "kind", "value", "source", "added_by", "note", "submission_id", "created_at" ] }, "SiteKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "allowed_origins": { "type": "array", "items": { "type": "string" } }, "theme": { "type": "object", "additionalProperties": { "type": "string" } }, "turnstile_required": { "type": "boolean" }, "normal_rate_per_minute": { "type": "integer" }, "revoked_at": { "type": [ "string", "null" ] }, "embed": { "type": "object", "properties": { "script": { "type": "string" }, "iframe": { "type": "string" } }, "required": [ "script", "iframe" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "public_key", "allowed_origins", "theme", "turnstile_required", "normal_rate_per_minute", "revoked_at", "embed", "created_at" ] }, "ForwardingTest": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "sent", "working", "failed" ] }, "sent_at": { "type": [ "string", "null" ] }, "passed_at": { "type": [ "string", "null" ] }, "result": { "type": [ "string", "null" ] }, "to": { "type": "string" } }, "required": [ "status", "sent_at", "passed_at", "result", "to" ] }, "Lead": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "maxLength": 200, "format": "email" }, "institution": { "type": "string", "maxLength": 200 }, "role": { "type": "string", "maxLength": 120 }, "segment": { "type": "string", "enum": [ "bank", "credit_union", "insurance", "utility", "other" ] }, "customers": { "type": "string", "enum": [ "<250K", "250K-1M", "1M-3M", "3M+" ] }, "message": { "type": "string", "maxLength": 4000 }, "source": { "type": "string", "maxLength": 200, "description": "Page path the form was submitted from." }, "turnstile_token": { "type": "string", "maxLength": 4000 }, "website": { "type": "string", "maxLength": 200, "description": "Honeypot. Leave empty." } }, "required": [ "name", "email" ] }, "PlatformTenant": { "allOf": [ { "$ref": "#/components/schemas/Tenant" }, { "type": "object", "properties": { "users": { "type": "integer" }, "domains_verified": { "type": "integer" }, "domains_total": { "type": "integer" }, "registrations_30d": { "type": "integer" }, "submissions_30d": { "type": "integer" }, "coverage_30d": { "type": [ "number", "null" ] }, "billing": { "type": [ "object", "null" ], "properties": { "stripe_customer_id": { "type": [ "string", "null" ] }, "band": { "type": [ "string", "null" ] }, "protected_customers": { "type": [ "integer", "null" ] }, "contract_end": { "type": [ "string", "null" ] } }, "required": [ "stripe_customer_id", "band", "protected_customers", "contract_end" ] } }, "required": [ "users", "domains_verified", "domains_total", "registrations_30d", "submissions_30d", "coverage_30d", "billing" ] } ] } }, "parameters": {} }, "paths": { "/healthz": { "get": { "tags": [ "System" ], "summary": "Health check", "description": "Returns ok when the Worker can reach D1. Neon is checked only when `?deep=1`.", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "deep", "in": "query" } ], "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/v1/me": { "get": { "tags": [ "Tenant" ], "summary": "Current user and tenant memberships", "security": [ { "Session": [] } ], "responses": { "200": { "description": "Me", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } } } } }, "/v1/tenant": { "get": { "tags": [ "Tenant" ], "summary": "Current tenant", "security": [ { "Session": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "Tenant" ], "summary": "Update tenant settings", "description": "Authoritative Mode and plan are read only here; a backoffice operator sets them.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPatch" } } } }, "responses": { "200": { "description": "Tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/users": { "get": { "tags": [ "Tenant" ], "summary": "List tenant users", "security": [ { "Session": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Users", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Tenant" ], "summary": "Invite a user", "description": "Creates the membership and emails a sign in link. The invitee signs in with a magic link or passkey.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUser" } } } }, "responses": { "201": { "description": "Invited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "409": { "description": "Already a member", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/users/{id}": { "patch": { "tags": [ "Tenant" ], "summary": "Change a user's role", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^usr_[0-9A-Z]{26}$", "example": "usr_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "analyst", "integrator", "viewer" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } } } }, "delete": { "tags": [ "Tenant" ], "summary": "Remove a user from the tenant", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^usr_[0-9A-Z]{26}$", "example": "usr_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } } } } }, "/v1/api-keys": { "get": { "tags": [ "Tenant" ], "summary": "List API keys", "security": [ { "Session": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Tenant" ], "summary": "Mint an API key", "description": "The secret is returned once and never stored. Test keys write to a sandbox partition and never send replies to real addresses.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKey" } } } }, "responses": { "201": { "description": "Key", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "properties": { "secret": { "type": "string" } }, "required": [ "secret" ] } ] } } } } } } }, "/v1/api-keys/{id}": { "delete": { "tags": [ "Tenant" ], "summary": "Revoke an API key", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^key_[0-9A-Z]{26}$", "example": "key_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "/v1/audit": { "get": { "tags": [ "Tenant" ], "summary": "Audit log", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Opaque cursor from a previous response." }, "required": false, "description": "Opaque cursor from a previous response.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "description": "Page size, 1 to 200, default 50.", "example": "50" }, "required": false, "description": "Page size, 1 to 200, default 50.", "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "action", "in": "query" } ], "responses": { "200": { "description": "Entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } } } } }, "/v1/domains": { "get": { "tags": [ "Domains" ], "summary": "List domains", "security": [ { "Session": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Domains" ], "summary": "Add a domain", "description": "Returns the TXT record to publish at `_fromenance.`. The domain is polled every hour for 24 hours, then daily once verified.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDomain" } } } }, "responses": { "201": { "description": "Domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } } } } }, "/v1/domains/{id}": { "get": { "tags": [ "Domains" ], "summary": "Domain detail", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Z]{26}$", "example": "dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } } } }, "patch": { "tags": [ "Domains" ], "summary": "Change domain roles", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Z]{26}$", "example": "dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainPatch" } } } }, "responses": { "200": { "description": "Domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } } } }, "delete": { "tags": [ "Domains" ], "summary": "Remove a domain", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Z]{26}$", "example": "dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } } } } }, "/v1/domains/{id}/check": { "post": { "tags": [ "Domains" ], "summary": "Re-check the TXT record now", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Z]{26}$", "example": "dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Domain after the check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } } } } }, "/v1/domains/{id}/reply-identity": { "post": { "tags": [ "Domains" ], "summary": "Create the branded reply identity", "description": "Creates `verify.` (or the given subdomain) as a Resend sending domain and returns the DKIM, SPF, and MX records to publish. Replies then come from `verify@verify.`.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Z]{26}$", "example": "dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "subdomain": { "type": "string", "pattern": "^[a-z0-9-]{1,30}$" } } } } } }, "responses": { "200": { "description": "Domain with reply identity records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } } } } }, "/v1/domains/{id}/reply-identity/verify": { "post": { "tags": [ "Domains" ], "summary": "Ask Resend to verify the reply identity records", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Z]{26}$", "example": "dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } } } } }, "/v1/communications": { "post": { "tags": [ "Communications" ], "summary": "Register one sent communication", "description": "Call at send time. Send only the recipient HMAC and the content fingerprint; never the address or the body. Returns the verify code to place in the footer. Supports `Idempotency-Key`.", "security": [ { "ApiKey": [ "register" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationRequest" } } } }, "responses": { "201": { "description": "Registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationResponse" } } } }, "400": { "description": "Validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "tags": [ "Communications" ], "summary": "Search registrations", "security": [ { "Session": [] }, { "ApiKey": [ "read" ] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "message_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "template_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "registered", "reserved", "expired" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "source_id", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Communications", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Communication" } } }, "required": [ "data" ] } } } } } } }, "/v1/communications/batch": { "post": { "tags": [ "Communications" ], "summary": "Register up to 1,000 communications", "description": "Per item results in input order. One bad item does not fail the batch. Rate limited at 6,000 items per minute.", "security": [ { "ApiKey": [ "register" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RegistrationRequest" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "ok": { "type": "boolean" }, "id": { "type": "string" }, "verify_code": { "type": "string" }, "expires_at": { "type": "string" }, "error": { "type": "string" } }, "required": [ "index", "ok" ] } }, "registered": { "type": "integer" }, "failed": { "type": "integer" } }, "required": [ "results", "registered", "failed" ] } } } } } } }, "/v1/communications/reserve": { "post": { "tags": [ "Communications" ], "summary": "Reserve a verify code before sending", "description": "For ESPs that need the code as a merge field before the send event exists. Complete it with `PATCH /v1/communications/{id}` or through the ESP webhook. Unfinished reservations expire after 24 hours and count as a coverage gap.", "security": [ { "ApiKey": [ "register" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveRequest" } } } }, "responses": { "201": { "description": "Reserved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationResponse" } } } } } } }, "/v1/communications/{id}": { "patch": { "tags": [ "Communications" ], "summary": "Complete a reserved registration", "security": [ { "ApiKey": [ "register" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^com_[0-9A-Z]{26}$", "example": "com_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteRequest" } } } }, "responses": { "200": { "description": "Communication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Communication" } } } } } }, "get": { "tags": [ "Communications" ], "summary": "Registration detail with verifications against it", "security": [ { "Session": [] }, { "ApiKey": [ "read" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^com_[0-9A-Z]{26}$", "example": "com_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Communication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Communication" } } } } } } }, "/v1/submissions": { "get": { "tags": [ "Submissions" ], "summary": "List submissions", "security": [ { "Session": [] }, { "ApiKey": [ "read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Opaque cursor from a previous response." }, "required": false, "description": "Opaque cursor from a previous response.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "description": "Page size, 1 to 200, default 50.", "example": "50" }, "required": false, "description": "Page size, 1 to 200, default 50.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "verified", "not_verified", "known_fraud" ] }, "required": false, "name": "outcome", "in": "query" }, { "schema": { "type": "string", "enum": [ "forward", "web", "api" ] }, "required": false, "name": "entry", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "replay", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "has_headers", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "code", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "submitter_hash", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "campaign_id", "in": "query" } ], "responses": { "200": { "description": "Submissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Submission" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } } } } }, "/v1/submissions/{id}": { "get": { "tags": [ "Submissions" ], "summary": "Submission detail", "description": "Extracted signals, verdict and rule, indicators with fraud list status, header summary, and a text preview with links disabled.", "security": [ { "Session": [] }, { "ApiKey": [ "read" ] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^sub_[0-9A-Z]{26}$", "example": "sub_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionDetail" } } } } } } }, "/v1/submissions/{id}/override": { "post": { "tags": [ "Submissions" ], "summary": "Analyst override", "description": "Marking fraud adds the submission's indicators and fingerprint to the tenant fraud list so later submissions resolve to Known fraud. Marking legitimate creates a registration retroactively and flags a coverage gap on the sending source.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^sub_[0-9A-Z]{26}$", "example": "sub_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "fraud", "legitimate" ] }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "outcome" ] } } } }, "responses": { "200": { "description": "Updated submission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Submission" } } } } } } }, "/v1/reply-templates": { "get": { "tags": [ "Reply templates" ], "summary": "All four reply templates", "security": [ { "Session": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReplyTemplate" } }, "variables": { "type": "array", "items": { "type": "string" } } }, "required": [ "data", "variables" ] } } } } } } }, "/v1/reply-templates/{outcome}": { "put": { "tags": [ "Reply templates" ], "summary": "Update a template", "description": "The body must include {{verdict_block}}; the locked verdict text cannot be edited and vouching language is refused.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "verified", "not_verified", "not_verified_authoritative", "known_fraud" ] }, "required": true, "name": "outcome", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 200 }, "body_mjml": { "type": "string", "minLength": 20, "maxLength": 50000 } }, "required": [ "subject", "body_mjml" ] } } } }, "responses": { "200": { "description": "Template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyTemplate" } } } } } } }, "/v1/reply-templates/{outcome}/preview": { "post": { "tags": [ "Reply templates" ], "summary": "Render a template with sample data", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "verified", "not_verified", "not_verified_authoritative", "known_fraud" ] }, "required": true, "name": "outcome", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string" }, "body_mjml": { "type": "string" } } } } } }, "responses": { "200": { "description": "Rendered", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "from": { "type": "string" } }, "required": [ "subject", "html", "text", "errors", "from" ] } } } } } } }, "/v1/reply-templates/{outcome}/test": { "post": { "tags": [ "Reply templates" ], "summary": "Send a test reply to yourself", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "verified", "not_verified", "not_verified_authoritative", "known_fraud" ] }, "required": true, "name": "outcome", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "to": { "type": "string" }, "from": { "type": "string" }, "id": { "type": "string" } }, "required": [ "ok", "to", "from", "id" ] } } } } } } }, "/v1/public/submit": { "post": { "tags": [ "Public" ], "summary": "Verify a message from the web page", "description": "Authenticated by site key and origin. Rate limited per IP and per key; a Turnstile token is required once a key exceeds its normal rate. Text and .eml return the verdict synchronously; screenshots return a poll token.", "security": [ { "SiteKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSubmit" } } } }, "responses": { "200": { "description": "Verdict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicVerdict" } } } }, "202": { "description": "Pending (screenshot)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicVerdict" } } } }, "428": { "description": "Turnstile required" }, "429": { "description": "Rate limited" } } } }, "/v1/public/verdict/{token}": { "get": { "tags": [ "Public" ], "summary": "Poll a screenshot submission", "security": [ { "SiteKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 8, "maxLength": 64 }, "required": true, "name": "token", "in": "path" } ], "responses": { "200": { "description": "Verdict or pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicVerdict" } } } } } } }, "/v1/sending-sources": { "get": { "tags": [ "Sending sources" ], "summary": "List sending sources with health", "security": [ { "Session": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Sources", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SendingSource" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Sending sources" ], "summary": "Create a sending source", "description": "Returns the webhook URL and the secret to configure at the provider. The secret is shown once. For Postmark the secret is the basic auth pair user:password.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSendingSource" } } } }, "responses": { "201": { "description": "Source", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendingSource" }, { "type": "object", "properties": { "secret": { "type": [ "string", "null" ] } }, "required": [ "secret" ] } ] } } } } } } }, "/v1/sending-sources/{id}": { "get": { "tags": [ "Sending sources" ], "summary": "Source detail", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^src_[0-9A-Z]{26}$", "example": "src_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingSource" } } } } } }, "patch": { "tags": [ "Sending sources" ], "summary": "Update a source", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^src_[0-9A-Z]{26}$", "example": "src_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "config": { "type": "object", "additionalProperties": { "type": "string" } }, "expected_daily_volume": { "type": [ "integer", "null" ], "minimum": 0 }, "silence_alert_minutes": { "type": "integer", "minimum": 5, "maximum": 20160 } } } } } }, "responses": { "200": { "description": "Source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingSource" } } } } } }, "delete": { "tags": [ "Sending sources" ], "summary": "Delete a source", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^src_[0-9A-Z]{26}$", "example": "src_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } } } } }, "/v1/sending-sources/{id}/rotate-secret": { "post": { "tags": [ "Sending sources" ], "summary": "Rotate the webhook secret", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^src_[0-9A-Z]{26}$", "example": "src_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "New secret, shown once", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" } }, "required": [ "secret" ] } } } } } } }, "/v1/sending-sources/{id}/test-event": { "post": { "tags": [ "Sending sources" ], "summary": "Run a synthetic send event through the adapter", "description": "Registers a sandbox communication for a test recipient so the integration engineer can see the source turn green without touching the provider.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^src_[0-9A-Z]{26}$", "example": "src_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "communication_id": { "type": "string" }, "verify_code": { "type": "string" } }, "required": [ "ok", "communication_id", "verify_code" ] } } } } } } }, "/v1/webhook-endpoints": { "get": { "tags": [ "Webhook endpoints" ], "summary": "List endpoints", "security": [ { "Session": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Endpoints", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "data", "events" ] } } } } } }, "post": { "tags": [ "Webhook endpoints" ], "summary": "Create an endpoint", "description": "Deliveries are signed with HMAC-SHA256 over `timestamp.body` using the returned secret (shown once), sent as X-Fromenance-Signature: v1= with X-Fromenance-Timestamp. Retried with backoff for 24 hours.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "verdict.created", "submission.replay_detected", "indicator.new", "campaign.detected" ] }, "minItems": 1 }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Endpoint with secret", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string" } }, "required": [ "secret" ] } ] } } } } } } }, "/v1/webhook-endpoints/{id}": { "patch": { "tags": [ "Webhook endpoints" ], "summary": "Update an endpoint", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^whe_[0-9A-Z]{26}$", "example": "whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "verdict.created", "submission.replay_detected", "indicator.new", "campaign.detected" ] }, "minItems": 1 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "description": { "type": [ "string", "null" ], "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "delete": { "tags": [ "Webhook endpoints" ], "summary": "Delete an endpoint", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^whe_[0-9A-Z]{26}$", "example": "whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } } } } }, "/v1/webhook-endpoints/{id}/deliveries": { "get": { "tags": [ "Webhook endpoints" ], "summary": "Delivery log", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^whe_[0-9A-Z]{26}$", "example": "whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deliveries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "required": [ "data" ] } } } } } } }, "/v1/webhook-endpoints/{id}/deliveries/{delivery_id}/replay": { "post": { "tags": [ "Webhook endpoints" ], "summary": "Replay a delivery", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "delivery_id", "in": "path" } ], "responses": { "200": { "description": "New delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } } }, "/v1/webhook-endpoints/{id}/test": { "post": { "tags": [ "Webhook endpoints" ], "summary": "Send a test verdict.created event", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^whe_[0-9A-Z]{26}$", "example": "whe_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delivery ids", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "delivery_ids" ] } } } } } } }, "/v1/stats": { "get": { "tags": [ "Stats" ], "summary": "Daily counts: registered, submitted, by outcome, by source, reply p95", "security": [ { "Session": [] }, { "ApiKey": [ "read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "1 to 365, default 30" }, "required": false, "description": "1 to 365, default 30", "name": "days", "in": "query" } ], "responses": { "200": { "description": "Stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stats" } } } } } } }, "/v1/indicators": { "get": { "tags": [ "Indicators" ], "summary": "List extracted indicators", "description": "Set `Accept: text/csv` or `Accept: application/stix+json` on /v1/indicators/export for exports.", "security": [ { "Session": [] }, { "ApiKey": [ "read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Opaque cursor from a previous response." }, "required": false, "description": "Opaque cursor from a previous response.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "description": "Page size, 1 to 200, default 50.", "example": "50" }, "required": false, "description": "Page size, 1 to 200, default 50.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "url", "domain", "email", "phone", "ip" ] }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "on_fraud_list", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "since", "in": "query" }, { "schema": { "type": "string", "enum": [ "low", "normal", "high" ] }, "required": false, "name": "priority", "in": "query" } ], "responses": { "200": { "description": "Indicators", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Indicator" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } } } } }, "/v1/fraud-list": { "get": { "tags": [ "Fraud list" ], "summary": "The tenant's block list", "security": [ { "Session": [] }, { "ApiKey": [ "read" ] } ], "responses": { "200": { "description": "Entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FraudListEntry" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Fraud list" ], "summary": "Add indicators to the fraud list", "description": "Entries come only from analyst action; nothing is added automatically from a single submission.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "url", "domain", "email", "phone", "ip" ] }, "value": { "type": "string", "minLength": 2, "maxLength": 2000 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "kind", "value" ] }, "minItems": 1, "maxItems": 500 } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Added", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FraudListEntry" } } }, "required": [ "added", "data" ] } } } } } } }, "/v1/fraud-list/{id}": { "delete": { "tags": [ "Fraud list" ], "summary": "Remove an entry", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } } } } }, "/v1/site-keys": { "get": { "tags": [ "Tenant" ], "summary": "List site keys with embed snippets", "security": [ { "Session": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Site keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SiteKey" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Tenant" ], "summary": "Create a site key", "security": [ { "Session": [] }, { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "allowed_origins": { "type": "array", "items": { "type": "string", "maxLength": 200, "format": "uri" }, "maxItems": 20 }, "theme": { "type": "object", "additionalProperties": { "type": "string" } }, "turnstile_required": { "type": "boolean" }, "normal_rate_per_minute": { "type": "integer", "minimum": 5, "maximum": 6000 } } } } } }, "responses": { "201": { "description": "Site key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteKey" } } } } } } }, "/v1/site-keys/{id}": { "patch": { "tags": [ "Tenant" ], "summary": "Update a site key", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^sk_[0-9A-Z]{26}$", "example": "sk_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "allowed_origins": { "type": "array", "items": { "type": "string", "maxLength": 200, "format": "uri" }, "maxItems": 20 }, "theme": { "type": "object", "additionalProperties": { "type": "string" } }, "turnstile_required": { "type": "boolean" }, "normal_rate_per_minute": { "type": "integer", "minimum": 5, "maximum": 6000 } } } } } }, "responses": { "200": { "description": "Site key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteKey" } } } } } }, "delete": { "tags": [ "Tenant" ], "summary": "Revoke a site key", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^sk_[0-9A-Z]{26}$", "example": "sk_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } } } } }, "/v1/search": { "get": { "tags": [ "Tenant" ], "summary": "Search submissions, registrations, and indicators", "security": [ { "Session": [] }, { "ApiKey": [ "read" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "required": true, "name": "q", "in": "query" } ], "responses": { "200": { "description": "Hits", "content": { "application/json": { "schema": { "type": "object", "properties": { "hits": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "submission", "communication", "indicator" ] }, "id": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "href": { "type": "string" } }, "required": [ "kind", "id", "title", "subtitle", "href" ] } } }, "required": [ "hits" ] } } } } } } }, "/v1/domains/{id}/forwarding-test": { "post": { "tags": [ "Domains" ], "summary": "Send the forwarding test message to verify@", "description": "The message carries a token. When the tenant's redirect rule delivers it to the tenant inbox with a DKIM or ARC pass for the domain, the rule is marked Working. Poll GET on the same path.", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Z]{26}$", "example": "dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardingTest" } } } } } }, "get": { "tags": [ "Domains" ], "summary": "Forwarding test status", "security": [ { "Session": [] }, { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Z]{26}$", "example": "dom_01J8Z9X0Q3K4M5N6P7R8S9T0V1" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardingTest" } } } } } } }, "/v1/setup": { "get": { "tags": [ "Tenant" ], "summary": "Onboarding progress derived from tenant state", "security": [ { "Session": [] }, { "ApiKey": [] } ], "responses": { "200": { "description": "Progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "steps": { "type": "object", "properties": { "tenant": { "type": "boolean" }, "domain_verified": { "type": "boolean" }, "forwarding_working": { "type": "boolean" }, "reply_identity": { "type": "boolean" }, "first_stream": { "type": "boolean" }, "footer_deployed": { "type": "boolean" } }, "required": [ "tenant", "domain_verified", "forwarding_working", "reply_identity", "first_stream", "footer_deployed" ] }, "live": { "type": "boolean" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string" }, "forwarding": { "$ref": "#/components/schemas/ForwardingTest" } }, "required": [ "id", "domain", "status", "forwarding" ] } } }, "required": [ "steps", "live", "domains" ] } } } } } } }, "/v1/leads": { "post": { "tags": [ "Public" ], "summary": "Submit a sales or pilot inquiry", "description": "Used by the fromenance.com contact and pilot forms. Rate limited per IP.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" } }, "required": [ "ok", "id" ] } } } }, "429": { "description": "Rate limited" } } } } }, "webhooks": {} }