{"openapi":"3.1.1","info":{"title":"Broodnet API","description":"REST API for Broodnet agent mailboxes, organizations, outbound policy, and webhooks.","version":"0.1.1"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"session-token","description":"Session token obtained from Better Auth sign-in"},"mailboxKey":{"type":"apiKey","in":"header","name":"x-mailbox-key","description":"Mailbox key for agent/CLI access to a specific mailbox"},"organizationApiKey":{"type":"apiKey","in":"header","name":"x-organization-key","description":"Organization API key for programmatic access to org-scoped resources"},"agentAuth":{"type":"http","scheme":"bearer","bearerFormat":"agent-jwt","description":"Short-lived agent JWT issued by the Agent Auth Protocol for capability-scoped access"}},"schemas":{}},"paths":{"/health":{"get":{"operationId":"getHealth","tags":["health"],"description":"Basic health check endpoint to verify the API is running","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"timestamp":{"type":"string","format":"date-time"}}}}}}}}},"/api/secret":{"get":{"operationId":"getApiSecret","tags":["health"],"description":"Basic auth check endpoint to verify the Auth workflow is working","security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"secret":{"type":"boolean"},"userId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/plans":{"get":{"operationId":"getApiPlans","tags":["plans"],"description":"List all publicly available plans","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["null","string"]},"price":{"type":"number"},"polarProductId":{"type":["null","string"]},"public":{"type":"boolean"},"available":{"type":"boolean"},"featured":{"type":"boolean"},"features":{"type":"object","properties":{"allowCustomMailboxNames":{"type":"boolean"},"allowCustomDomains":{"type":"boolean"},"allowWebhooks":{"type":"boolean"},"allowOutboundWhitelist":{"type":"boolean"},"allowOutboundReplyWindow":{"type":"boolean"}}},"limits":{"type":"object","properties":{"maxMailboxes":{"type":"number"},"maxMailboxSize":{"type":"number"},"maxCustomDomains":{"type":"number"},"maxWebhooks":{"type":"number"}}}}}}}}}}}},"/api/mailboxes":{"post":{"operationId":"postApiMailboxes","tags":["mailboxes"],"description":"Create a new mailbox. Returns a one-time token — store it securely, it will not be shown again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"localPart":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9.\\-_]+$"},"name":{"type":"string","maxLength":255}},"additionalProperties":false}}}},"security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"agentAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"createdBy":{"type":"string","maxLength":36},"agentId":{"type":["null","string"]},"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"localPart":{"type":"string","maxLength":64},"domain":{"type":"string"},"address":{"type":"string"},"suspended":{"type":["null","boolean"]},"syncStatus":{"type":"string","enum":["pending","synced","failed"]},"syncError":{"type":["null","string"]},"lastSyncedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"logo":{"type":["null","string"]},"plan":{"type":"string"},"subdomain":{"type":"string"},"polar_subscription_id":{"type":["null","string"]},"polar_customer_id":{"type":["null","string"]}},"required":["id","name","slug","logo","plan","subdomain","polar_subscription_id","polar_customer_id"],"additionalProperties":false},"createdByUser":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"image":{"type":["null","string"]}},"required":["id","name","image"],"additionalProperties":false},"token":{"type":"string"}},"required":["id","organizationId","createdBy","agentId","name","localPart","domain","address","suspended","syncStatus","syncError","lastSyncedAt","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"description":"Bad request","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"get":{"operationId":"getApiMailboxes","tags":["mailboxes"],"description":"List mailboxes for the active organization","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"agentAuth":[]},{"bearerAuth":[]},{"organizationApiKey":[]},{"agentAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"createdBy":{"type":"string","maxLength":36},"agentId":{"type":["null","string"]},"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"localPart":{"type":"string","maxLength":64},"domain":{"type":"string"},"address":{"type":"string"},"suspended":{"type":["null","boolean"]},"syncStatus":{"type":"string","enum":["pending","synced","failed"]},"syncError":{"type":["null","string"]},"lastSyncedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"logo":{"type":["null","string"]},"plan":{"type":"string"},"subdomain":{"type":"string"},"polar_subscription_id":{"type":["null","string"]},"polar_customer_id":{"type":["null","string"]}},"required":["id","name","slug","logo","plan","subdomain","polar_subscription_id","polar_customer_id"],"additionalProperties":false},"createdByUser":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"image":{"type":["null","string"]}},"required":["id","name","image"],"additionalProperties":false}},"required":["id","organizationId","createdBy","agentId","name","localPart","domain","address","suspended","syncStatus","syncError","lastSyncedAt","createdAt","updatedAt"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/mailboxes/{id}":{"patch":{"operationId":"patchApiMailboxesById","tags":["mailboxes"],"description":"Update a mailbox (name only). Address/localPart are immutable.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255}},"additionalProperties":false}}}},"security":[{"bearerAuth":[]},{"organizationApiKey":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"createdBy":{"type":"string","maxLength":36},"agentId":{"type":["null","string"]},"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"localPart":{"type":"string","maxLength":64},"domain":{"type":"string"},"address":{"type":"string"},"suspended":{"type":["null","boolean"]},"syncStatus":{"type":"string","enum":["pending","synced","failed"]},"syncError":{"type":["null","string"]},"lastSyncedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"logo":{"type":["null","string"]},"plan":{"type":"string"},"subdomain":{"type":"string"},"polar_subscription_id":{"type":["null","string"]},"polar_customer_id":{"type":["null","string"]}},"required":["id","name","slug","logo","plan","subdomain","polar_subscription_id","polar_customer_id"],"additionalProperties":false},"createdByUser":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"image":{"type":["null","string"]}},"required":["id","name","image"],"additionalProperties":false}},"required":["id","organizationId","createdBy","agentId","name","localPart","domain","address","suspended","syncStatus","syncError","lastSyncedAt","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"description":"Bad request","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"get":{"operationId":"getApiMailboxesById","tags":["mailboxes"],"description":"Get a single mailbox by ID","security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"bearerAuth":[]},{"organizationApiKey":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"createdBy":{"type":"string","maxLength":36},"agentId":{"type":["null","string"]},"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"localPart":{"type":"string","maxLength":64},"domain":{"type":"string"},"address":{"type":"string"},"suspended":{"type":["null","boolean"]},"syncStatus":{"type":"string","enum":["pending","synced","failed"]},"syncError":{"type":["null","string"]},"lastSyncedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"logo":{"type":["null","string"]},"plan":{"type":"string"},"subdomain":{"type":"string"},"polar_subscription_id":{"type":["null","string"]},"polar_customer_id":{"type":["null","string"]}},"required":["id","name","slug","logo","plan","subdomain","polar_subscription_id","polar_customer_id"],"additionalProperties":false},"createdByUser":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"image":{"type":["null","string"]}},"required":["id","name","image"],"additionalProperties":false}},"required":["id","organizationId","createdBy","agentId","name","localPart","domain","address","suspended","syncStatus","syncError","lastSyncedAt","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"delete":{"operationId":"deleteApiMailboxesById","tags":["mailboxes"],"description":"Delete a mailbox. Deprovisions on Mailserver and removes the record.","security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"agentAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/mailboxes/{id}/rotate-token":{"post":{"operationId":"postApiMailboxesByIdRotateToken","tags":["mailboxes"],"description":"Rotate the mailbox token. Returns a new one-time token — store it securely, the old token stops working immediately.","security":[{"bearerAuth":[]},{"organizationApiKey":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/mailbox/consent":{"get":{"operationId":"getApiMailboxConsent","tags":["mailboxes","outbound-policy"],"description":"Return outbound-consent status for the authenticated mailbox.","security":[{"mailboxKey":[]},{"mailboxKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"mailbox":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"organizationName":{"type":"string"},"policy":{"type":"object","properties":{"mute":{"type":"boolean"},"enableWhitelist":{"type":"boolean"},"enableReplyWindow":{"type":"boolean"},"replyWindowHours":{"type":"number"},"effectiveEnableWhitelist":{"type":"boolean"},"effectiveEnableReplyWindow":{"type":"boolean"},"planAllowsWhitelist":{"type":"boolean"},"planAllowsReplyWindow":{"type":"boolean"}},"required":["mute","enableWhitelist","enableReplyWindow","replyWindowHours","effectiveEnableWhitelist","effectiveEnableReplyWindow","planAllowsWhitelist","planAllowsReplyWindow"],"additionalProperties":false},"canRequest":{"type":"boolean"},"reason":{"type":["null","string"]}},"required":["mailbox","organizationName","policy","canRequest","reason"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/mailbox/consent-requests":{"get":{"operationId":"getApiMailboxConsentRequests","tags":["mailboxes","outbound-policy"],"description":"List outbound recipient consent rows for the authenticated mailbox organization.","security":[{"mailboxKey":[]},{"mailboxKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"email":{"type":"string","maxLength":320},"status":{"type":"string","enum":["pending","approved","denied","revoked"]},"note":{"type":["null","string"]},"requestedBy":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}]},"requestedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deniedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"isExpired":{"type":"boolean"}},"required":["id","organizationId","email","status","note","requestedBy","requestedAt","approvedAt","deniedAt","expiresAt"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"post":{"operationId":"postApiMailboxConsentRequests","tags":["mailboxes","outbound-policy"],"description":"Request external recipient consent from the authenticated mailbox.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{},"note":{}},"required":["email"],"additionalProperties":false}}}},"security":[{"mailboxKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"recipient":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"email":{"type":"string","maxLength":320},"status":{"type":"string","enum":["pending","approved","denied","revoked"]},"note":{"type":["string","null"]},"requestedBy":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}]},"requestedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deniedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"isExpired":{"type":"boolean"}},"required":["id","organizationId","email","status","note","requestedBy","requestedAt","approvedAt","deniedAt","expiresAt"],"additionalProperties":false},{"type":"null"}]},"result":{"type":"string","enum":["created","already_pending","already_approved","not_required"]},"message":{"type":"string"}},"required":["recipient","result"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"description":"Bad request","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/mailbox/connect":{"get":{"operationId":"getApiMailboxConnect","tags":["mailboxes"],"description":"Verify mailbox API key and return IMAP connection config. Used by the CLI during `broodnet login`.","security":[{"mailboxKey":[]},{"mailboxKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"host":{"type":"string"},"port":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"mailbox":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"from":{"type":"string"}},"required":["host","port","mailbox","from"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/mailbox/status":{"get":{"operationId":"getApiMailboxStatus","tags":["mailboxes"],"description":"Return live storage, message count, and mailbox health for the authenticated mailbox.","security":[{"mailboxKey":[]},{"mailboxKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"quota":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quotaUsed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"messages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"percentInUse":{"type":"number"},"active":{"type":"boolean"},"imapEnabled":{"type":"boolean"},"smtpEnabled":{"type":"boolean"}},"required":["quota","quotaUsed","messages","percentInUse","active","imapEnabled","smtpEnabled"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/mailbox/validate-from":{"post":{"operationId":"postApiMailboxValidateFrom","tags":["mailboxes"],"description":"Verify whether a From address is allowed for the authenticated mailbox. Allows canonical mailbox and localpart@verified-custom-domain aliases.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","minLength":3,"maxLength":512}},"required":["from"],"additionalProperties":false}}}},"security":[{"mailboxKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"normalizedFrom":{"type":["null","string"]},"reason":{"type":["null","string"]}},"required":["valid","normalizedFrom","reason"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"description":"Bad request","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/billing/subscription":{"get":{"operationId":"getApiBillingSubscription","tags":["billing"],"description":"Get the current subscription status for the active organization","security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":["null","string"]},"currentPeriodEnd":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"cancelAtPeriodEnd":{"type":["null","boolean"]},"productId":{"type":["null","string"]},"polarSubscriptionId":{"type":["null","string"]}},"required":["status","currentPeriodEnd","cancelAtPeriodEnd","productId","polarSubscriptionId"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/billing/resume":{"post":{"operationId":"postApiBillingResume","tags":["billing"],"description":"Resume a canceled or paused subscription. Only works for subscriptions that have not yet expired.","security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/organization/usage":{"get":{"operationId":"getApiOrganizationUsage","tags":["organization"],"description":"Fetches the current usage for the active organization","security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"bearerAuth":[]},{"organizationApiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"planId":{"description":"Identifier of the organization's current plan (e.g. 'free', 'paid'), or null if no plan is active","type":["null","string"]},"mailboxes":{"type":"object","properties":{"total":{"type":"number","description":"Current total number of active mailboxes"},"max":{"type":"number","description":"Maximum number of mailboxes allowed (0 = disabled, -1 = unlimited)"}},"required":["total","max"],"additionalProperties":false,"description":"Current number of active mailboxes and the maximum allowed by the plan"},"messages":{"type":"object","properties":{"total":{"type":"number","description":"Current total number of messages across all mailboxes"},"max":{"type":"number","description":"Maximum number of messages (0 = disabled, -1 = unlimited)"}},"required":["total","max"],"additionalProperties":false,"description":"Current number of messages and the maximum allowed by the plan"},"storage":{"type":"object","properties":{"total":{"type":"number","description":"Current total storage used across all mailboxes in megabytes"},"max":{"type":"number","description":"Maximum storage in megabytes (0 = disabled, -1 = unlimited)"}},"required":["total","max"],"additionalProperties":false,"description":"Current storage usage and the maximum allowed by the plan in megabytes"}},"required":["planId","mailboxes","messages","storage"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/organization/domains":{"get":{"operationId":"getApiOrganizationDomains","tags":["organizations"],"description":"List all custom alias domains for the active organization","security":[{"bearerAuth":[]},{"agentAuth":[]},{"bearerAuth":[]},{"agentAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"domain":{"type":"string","maxLength":255},"syncStatus":{"type":"string","enum":["pending","synced","failed"]},"syncError":{"type":["null","string"]},"lastSyncedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"token":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"dnsStatus":{"type":"string","maxLength":20},"verifiedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"checkOwnership":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkSpf":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkDkim":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkMx":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","domain","syncStatus","syncError","lastSyncedAt","token","dnsStatus","verifiedAt","lastCheck","checkOwnership","checkSpf","checkDkim","checkMx","createdAt"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"post":{"operationId":"postApiOrganizationDomains","tags":["organizations"],"description":"Add a custom alias domain for the active organization (paid feature). The domain will be provisioned on the Mailserver asynchronously — check syncStatus for readiness.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","pattern":"^(?!-)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$"}},"required":["domain"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]},{"agentAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"domain":{"type":"string","maxLength":255},"syncStatus":{"type":"string","enum":["pending","synced","failed"]},"syncError":{"type":["null","string"]},"lastSyncedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"token":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"dnsStatus":{"type":"string","maxLength":20},"verifiedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"checkOwnership":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkSpf":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkDkim":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkMx":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","domain","syncStatus","syncError","lastSyncedAt","token","dnsStatus","verifiedAt","lastCheck","checkOwnership","checkSpf","checkDkim","checkMx","createdAt"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"description":"Bad request","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/organization/domains/{id}":{"get":{"operationId":"getApiOrganizationDomainsById","tags":["organizations"],"description":"Fetch a single custom domain record including its live DKIM TXT value from the Mailserver","security":[{"bearerAuth":[]},{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"domain":{"type":"string","maxLength":255},"syncStatus":{"type":"string","enum":["pending","synced","failed"]},"syncError":{"type":["null","string"]},"lastSyncedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"token":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"dnsStatus":{"type":"string","maxLength":20},"verifiedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"checkOwnership":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkSpf":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkDkim":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkMx":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"dkimTxt":{"type":["null","string"]}},"required":["id","organizationId","domain","syncStatus","syncError","lastSyncedAt","token","dnsStatus","verifiedAt","lastCheck","checkOwnership","checkSpf","checkDkim","checkMx","createdAt","dkimTxt"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"delete":{"operationId":"deleteApiOrganizationDomainsById","tags":["organizations"],"description":"Remove a custom alias domain from the active organization. This will also deprovision the domain from the Mailserver. WARNING: any mail sent to addresses on this domain will stop being delivered.","security":[{"bearerAuth":[]},{"agentAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/organization/domains/{id}/verify":{"post":{"operationId":"postApiOrganizationDomainsByIdVerify","tags":["organizations"],"description":"Trigger a live DNS check for the ownership TXT record and update dnsStatus. Returns the updated domain record.","security":[{"bearerAuth":[]},{"agentAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"domain":{"type":"string","maxLength":255},"syncStatus":{"type":"string","enum":["pending","synced","failed"]},"syncError":{"type":["null","string"]},"lastSyncedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"token":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"dnsStatus":{"type":"string","maxLength":20},"verifiedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"checkOwnership":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkSpf":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkDkim":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkMx":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","domain","syncStatus","syncError","lastSyncedAt","token","dnsStatus","verifiedAt","lastCheck","checkOwnership","checkSpf","checkDkim","checkMx","createdAt"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/organization/domains/{id}/rotate-token":{"post":{"operationId":"postApiOrganizationDomainsByIdRotateToken","tags":["organizations"],"description":"Regenerate the ownership verification token for a custom domain. Resets dnsStatus to pending and clears all DNS check results. The user must republish the broodnet-graft= TXT record and re-verify.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"domain":{"type":"string","maxLength":255},"syncStatus":{"type":"string","enum":["pending","synced","failed"]},"syncError":{"type":["null","string"]},"lastSyncedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"token":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"dnsStatus":{"type":"string","maxLength":20},"verifiedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"checkOwnership":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkSpf":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkDkim":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkMx":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","domain","syncStatus","syncError","lastSyncedAt","token","dnsStatus","verifiedAt","lastCheck","checkOwnership","checkSpf","checkDkim","checkMx","createdAt"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/organization/domains/{id}/rotate-dkim":{"post":{"operationId":"postApiOrganizationDomainsByIdRotateDkim","tags":["organizations"],"description":"Regenerate the DKIM key for the custom domain. The user must update their DNS DKIM TXT record.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"domain":{"type":"string","maxLength":255},"syncStatus":{"type":"string","enum":["pending","synced","failed"]},"syncError":{"type":["null","string"]},"lastSyncedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"token":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"dnsStatus":{"type":"string","maxLength":20},"verifiedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"checkOwnership":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkSpf":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkDkim":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"checkMx":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","domain","syncStatus","syncError","lastSyncedAt","token","dnsStatus","verifiedAt","lastCheck","checkOwnership","checkSpf","checkDkim","checkMx","createdAt"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/admin/api-keys":{"get":{"operationId":"getApiAdminApiKeys","tags":["admin"],"description":"List all API keys across organizations (admin only)","parameters":[{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/admin/api-keys/{keyId}":{"delete":{"operationId":"deleteApiAdminApiKeysByKeyId","tags":["admin"],"description":"Delete an API key (admin only)","parameters":[{"schema":{"type":"string"},"in":"path","name":"keyId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/admin/agents":{"get":{"operationId":"getApiAdminAgents","tags":["admin"],"description":"List all agents across users (admin only)","parameters":[{"schema":{"type":"string"},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"userId","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false},{"schema":{"type":"string","enum":["name","status","createdAt","expiresAt"]},"in":"query","name":"orderBy","required":false},{"schema":{"type":"string","enum":["asc","desc"]},"in":"query","name":"orderDir","required":false}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/admin/agents/stats":{"get":{"operationId":"getApiAdminAgentsStats","tags":["admin"],"description":"Global agent + activity stats (admin only)","security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/admin/agents/{agentId}/revoke":{"post":{"operationId":"postApiAdminAgentsByAgentIdRevoke","tags":["admin"],"description":"Revoke an agent (admin only, no ownership check)","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/admin/agents/{agentId}":{"delete":{"operationId":"deleteApiAdminAgentsByAgentId","tags":["admin"],"description":"Delete an agent (admin only, no ownership check)","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"get":{"operationId":"getApiAdminAgentsByAgentId","tags":["admin"],"description":"Get a single agent by ID (admin only, no ownership check)","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/admin/agents/{agentId}/activity":{"get":{"operationId":"getApiAdminAgentsByAgentIdActivity","tags":["admin"],"description":"Agent activity log (admin only, no ownership check)","parameters":[{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/admin/hosts":{"get":{"operationId":"getApiAdminHosts","tags":["admin"],"description":"List all hosts across users (admin only)","parameters":[{"schema":{"type":"string"},"in":"query","name":"userId","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false},{"schema":{"type":"string","enum":["name","status","createdAt"]},"in":"query","name":"orderBy","required":false},{"schema":{"type":"string","enum":["asc","desc"]},"in":"query","name":"orderDir","required":false}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/admin/hosts/{hostId}/revoke":{"post":{"operationId":"postApiAdminHostsByHostIdRevoke","tags":["admin"],"description":"Revoke a host (admin only, no ownership check)","parameters":[{"schema":{"type":"string"},"in":"path","name":"hostId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/admin/users/{userId}":{"get":{"operationId":"getApiAdminUsersByUserId","tags":["admin"],"description":"Get user details with organizations, mailboxes, and custom domains (admin only)","parameters":[{"schema":{"type":"string"},"in":"path","name":"userId","required":true}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/admin/organizations/{orgId}/plan":{"post":{"operationId":"postApiAdminOrganizationsByOrgIdPlan","tags":["admin"],"description":"Override an organization's plan (admin only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string"}},"required":["plan"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/account":{"delete":{"operationId":"deleteApiAccount","tags":["account"],"description":"Permanently delete the authenticated user's account. This will delete all organizations where the user is the sole member, including all mailboxes, emails and custom domains. The user record is anonymized for audit purposes. Cannot be undone.","security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agents":{"get":{"operationId":"getApiAgents","tags":["agents"],"description":"Paginated agent list scoped to the user's active organization","parameters":[{"schema":{"type":"string","enum":["user","org"]},"in":"query","name":"scope","required":false},{"schema":{"type":"string"},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"hostId","required":false},{"schema":{"type":"string","enum":["delegated","autonomous"]},"in":"query","name":"mode","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"unowned","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false},{"schema":{"type":"string","enum":["name","status","createdAt","expiresAt"]},"in":"query","name":"orderBy","required":false},{"schema":{"type":"string","enum":["asc","desc"]},"in":"query","name":"orderDir","required":false}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agents/{agentId}":{"get":{"operationId":"getApiAgentsByAgentId","tags":["agents"],"description":"Agent detail (ownership-verified, org-admin fallback)","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"delete":{"operationId":"deleteApiAgentsByAgentId","tags":["agents"],"description":"Hard-delete an agent (cascades grants + approval requests). Ownership-verified.","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agents/{agentId}/activity":{"get":{"operationId":"getApiAgentsByAgentIdActivity","tags":["agents"],"description":"Paginated activity log for an agent (ownership-verified)","parameters":[{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"delete":{"operationId":"deleteApiAgentsByAgentIdActivity","tags":["agents"],"description":"Delete all activity records for an agent (ownership-verified)","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agents/{agentId}/revoke-grant":{"post":{"operationId":"postApiAgentsByAgentIdRevokeGrant","tags":["agents"],"description":"Revoke a single capability grant from an agent. Ownership-verified.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["capability"],"properties":{"capability":{"type":"string"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agents/{agentId}/renew":{"post":{"operationId":"postApiAgentsByAgentIdRenew","tags":["agents"],"description":"Renew an expired agent credential (not revoked). Resets lifetime based on plan tier.","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agents/pending-approvals":{"get":{"operationId":"getApiAgentsPendingApprovals","tags":["agents"],"description":"List pending approval requests for agents owned by the authenticated user","security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/agents/{agentId}/deny":{"post":{"operationId":"postApiAgentsByAgentIdDeny","tags":["agents"],"description":"Deny all pending approval requests for an agent owned by the authenticated user","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/hosts":{"get":{"operationId":"getApiHosts","tags":["hosts"],"description":"Paginated host list scoped to the user's active organization","parameters":[{"schema":{"type":"string","enum":["user","org"]},"in":"query","name":"scope","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false},{"schema":{"type":"string","enum":["name","status","createdAt"]},"in":"query","name":"orderBy","required":false},{"schema":{"type":"string","enum":["asc","desc"]},"in":"query","name":"orderDir","required":false}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/hosts/{hostId}":{"get":{"operationId":"getApiHostsByHostId","tags":["hosts"],"description":"Host detail with linked agent count (ownership-verified)","parameters":[{"schema":{"type":"string"},"in":"path","name":"hostId","required":true}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"delete":{"operationId":"deleteApiHostsByHostId","tags":["hosts"],"description":"Hard-delete a host (cascades linked agents + approvals). Ownership-verified.","parameters":[{"schema":{"type":"string"},"in":"path","name":"hostId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/hosts/{hostId}/revoke":{"post":{"operationId":"postApiHostsByHostIdRevoke","tags":["hosts"],"description":"Revoke a host (sets status to revoked). Ownership-verified.","parameters":[{"schema":{"type":"string"},"in":"path","name":"hostId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/hosts/{hostId}/rotate-key":{"post":{"operationId":"postApiHostsByHostIdRotateKey","tags":["hosts"],"description":"Rotate a host's public key. Ownership-verified.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["publicKey"],"properties":{"publicKey":{"type":"string"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"hostId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/hosts/{hostId}/regenerate-enrollment-token":{"post":{"operationId":"postApiHostsByHostIdRegenerateEnrollmentToken","tags":["hosts"],"description":"Regenerate enrollment token for a pending_enrollment host. Returns the new plaintext token (one-time display).","parameters":[{"schema":{"type":"string"},"in":"path","name":"hostId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/hosts/{hostId}/transfer":{"post":{"operationId":"postApiHostsByHostIdTransfer","tags":["hosts"],"description":"Transfer host ownership to another user in the same organization. Both users receive a notification.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["toUserId"],"properties":{"toUserId":{"type":"string"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"hostId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/hosts/{hostId}/agents":{"get":{"operationId":"getApiHostsByHostIdAgents","tags":["hosts"],"description":"Paginated agent list for a specific host (ownership-verified via host.userId)","parameters":[{"schema":{"type":"string"},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["delegated","autonomous"]},"in":"query","name":"mode","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false},{"schema":{"type":"string","enum":["name","status","createdAt","expiresAt"]},"in":"query","name":"orderBy","required":false},{"schema":{"type":"string","enum":["asc","desc"]},"in":"query","name":"orderDir","required":false},{"schema":{"type":"string"},"in":"path","name":"hostId","required":true}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/notifications":{"get":{"operationId":"getApiNotifications","tags":["notifications"],"description":"Paginated list of notifications for the authenticated user, unread-first.","parameters":[{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false}],"security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/notifications/unread-count":{"get":{"operationId":"getApiNotificationsUnreadCount","tags":["notifications"],"description":"Returns the count of unread notifications for the authenticated user.","security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/notifications/{id}/read":{"post":{"operationId":"postApiNotificationsByIdRead","tags":["notifications"],"description":"Mark a single notification as read.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/notifications/read-all":{"post":{"operationId":"postApiNotificationsReadAll","tags":["notifications"],"description":"Mark all notifications as read for the authenticated user.","security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/notifications/preferences":{"get":{"operationId":"getApiNotificationsPreferences","tags":["notifications"],"description":"Returns notification preferences for the authenticated user.","security":[{"bearerAuth":[]},{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"put":{"operationId":"putApiNotificationsPreferences","tags":["notifications"],"description":"Update notification preferences for the authenticated user.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["preferences"],"properties":{"preferences":{"type":"array","items":{"type":"object","required":["eventType","emailEnabled","inAppEnabled"],"properties":{"eventType":{"type":"string"},"emailEnabled":{"type":"boolean"},"inAppEnabled":{"type":"boolean"}}}}}}}}},"security":[{"bearerAuth":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/audit/events":{"get":{"operationId":"getApiAuditEvents","tags":["audit"],"description":"Paginated, filterable audit event log for the active organization.","parameters":[{"schema":{"type":"string"},"in":"query","name":"mailboxId","required":false},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"in":"query","name":"eventType","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string","enum":["user","agent","mailbox","system"]},"in":"query","name":"actorType","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"to","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","enum":["createdAt","eventType","actorType","details"],"default":"createdAt"},"in":"query","name":"orderBy","required":false},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"in":"query","name":"orderDir","required":false}],"security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"bearerAuth":[]},{"organizationApiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"mailboxId":{"type":["null","string"]},"actorType":{"type":"string","enum":["user","agent","mailbox","system"]},"actorId":{"type":"string"},"eventType":{"type":"string","enum":["email_received","email_sent","email_blocked","mailbox_created","mailbox_deleted","mailbox_key_rotated","domain_created","domain_verified","organization_created","member_added","member_removed","member_role_changed","plan_changed","payment_processed","payment_failed","webhook_created","webhook_deleted","webhook_secret_rotated","outbound_policy_updated","outbound_consent_requested","outbound_consent_approved","outbound_consent_denied","outbound_recipient_dismissed","outbound_recipient_revoked","api_key_used"]},"payload":{"anyOf":[{},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","mailboxId","actorType","actorId","eventType","payload","createdAt"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/webhooks":{"post":{"operationId":"postApiWebhooks","tags":["webhooks"],"description":"Create a new webhook. Returns the signing secret once — store it securely, it will not be shown again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"eventTypes":{"minItems":1,"type":"array","items":{"type":"string","enum":["email_received","email_sent","email_blocked","mailbox_created","mailbox_deleted","outbound_consent_requested","outbound_consent_approved","outbound_consent_denied"]}},"mailboxId":{"type":"string","minLength":1},"description":{"type":"string","maxLength":255},"authHeader":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$"},"value":{"type":"string","minLength":1,"maxLength":4096}},"required":["name","value"],"additionalProperties":false}},"required":["url","eventTypes"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"agentAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"mailboxId":{"type":["null","string"]},"url":{"type":"string"},"authHeaderName":{"type":["null","string"]},"eventTypes":{"type":"array","items":{"type":"string","enum":["email_received","email_sent","email_blocked","mailbox_created","mailbox_deleted","outbound_consent_requested","outbound_consent_approved","outbound_consent_denied"]}},"active":{"type":"boolean"},"description":{"type":["null","string"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"secret":{"type":"string"}},"required":["id","organizationId","mailboxId","url","authHeaderName","eventTypes","active","description","createdAt","updatedAt","secret"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"description":"Bad request","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"get":{"operationId":"getApiWebhooks","tags":["webhooks"],"description":"List all webhooks for the active organization","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"agentAuth":[]},{"bearerAuth":[]},{"organizationApiKey":[]},{"agentAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"mailboxId":{"type":["null","string"]},"url":{"type":"string"},"authHeaderName":{"type":["null","string"]},"eventTypes":{"type":"array","items":{"type":"string","enum":["email_received","email_sent","email_blocked","mailbox_created","mailbox_deleted","outbound_consent_requested","outbound_consent_approved","outbound_consent_denied"]}},"active":{"type":"boolean"},"description":{"type":["null","string"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","mailboxId","url","authHeaderName","eventTypes","active","description","createdAt","updatedAt"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/webhooks/{id}":{"get":{"operationId":"getApiWebhooksById","tags":["webhooks"],"description":"Get a single webhook by ID","security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"bearerAuth":[]},{"organizationApiKey":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"mailboxId":{"type":["null","string"]},"url":{"type":"string"},"authHeaderName":{"type":["null","string"]},"eventTypes":{"type":"array","items":{"type":"string","enum":["email_received","email_sent","email_blocked","mailbox_created","mailbox_deleted","outbound_consent_requested","outbound_consent_approved","outbound_consent_denied"]}},"active":{"type":"boolean"},"description":{"type":["null","string"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","mailboxId","url","authHeaderName","eventTypes","active","description","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"patch":{"operationId":"patchApiWebhooksById","tags":["webhooks"],"description":"Update a webhook (url, eventTypes, active, description, authentication header)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"eventTypes":{"minItems":1,"type":"array","items":{"type":"string","enum":["email_received","email_sent","email_blocked","mailbox_created","mailbox_deleted","outbound_consent_requested","outbound_consent_approved","outbound_consent_denied"]}},"active":{"type":"boolean"},"description":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"authHeader":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$"},"value":{"type":"string","minLength":1,"maxLength":4096}},"required":["name","value"],"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false}}}},"security":[{"bearerAuth":[]},{"organizationApiKey":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"mailboxId":{"type":["null","string"]},"url":{"type":"string"},"authHeaderName":{"type":["null","string"]},"eventTypes":{"type":"array","items":{"type":"string","enum":["email_received","email_sent","email_blocked","mailbox_created","mailbox_deleted","outbound_consent_requested","outbound_consent_approved","outbound_consent_denied"]}},"active":{"type":"boolean"},"description":{"type":["null","string"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","mailboxId","url","authHeaderName","eventTypes","active","description","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"description":"Bad request","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"delete":{"operationId":"deleteApiWebhooksById","tags":["webhooks"],"description":"Delete a webhook. All pending deliveries are canceled.","security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"agentAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/webhooks/{id}/rotate-secret":{"post":{"operationId":"postApiWebhooksByIdRotateSecret","tags":["webhooks"],"description":"Rotate the webhook signing secret. Returns the new secret once — store it securely, the old secret stops working immediately.","security":[{"bearerAuth":[]},{"organizationApiKey":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"mailboxId":{"type":["null","string"]},"url":{"type":"string"},"authHeaderName":{"type":["null","string"]},"eventTypes":{"type":"array","items":{"type":"string","enum":["email_received","email_sent","email_blocked","mailbox_created","mailbox_deleted","outbound_consent_requested","outbound_consent_approved","outbound_consent_denied"]}},"active":{"type":"boolean"},"description":{"type":["null","string"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"secret":{"type":"string"}},"required":["id","organizationId","mailboxId","url","authHeaderName","eventTypes","active","description","createdAt","updatedAt","secret"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/webhooks/{webhookId}/deliveries":{"get":{"operationId":"getApiWebhooksByWebhookIdDeliveries","tags":["webhooks"],"description":"List delivery attempts for a webhook, with optional status/event filters","parameters":[{"schema":{"type":"string","enum":["pending","success","failed","exhausted"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["email_received","email_sent","email_blocked","mailbox_created","mailbox_deleted","outbound_consent_requested","outbound_consent_approved","outbound_consent_denied"]},"in":"query","name":"eventType","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"webhookId","required":true}],"security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"bearerAuth":[]},{"organizationApiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"webhookId":{"type":"string"},"auditEventId":{"type":"string"},"eventType":{"type":"string","enum":["email_received","email_sent","email_blocked","mailbox_created","mailbox_deleted","outbound_consent_requested","outbound_consent_approved","outbound_consent_denied"]},"status":{"type":"string","enum":["pending","success","failed","exhausted"]},"attempts":{"type":"number"},"maxAttempts":{"type":"number"},"lastError":{"type":["null","string"]},"responseCode":{"type":["null","number"]},"payload":{},"nextRetryAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","webhookId","auditEventId","eventType","status","attempts","maxAttempts","lastError","responseCode","payload","nextRetryAt","createdAt"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/webhooks/{webhookId}/deliveries/{id}":{"get":{"operationId":"getApiWebhooksByWebhookIdDeliveriesById","tags":["webhooks"],"description":"Get a single delivery attempt by ID","security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"bearerAuth":[]},{"organizationApiKey":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"webhookId","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"webhookId":{"type":"string"},"auditEventId":{"type":"string"},"eventType":{"type":"string","enum":["email_received","email_sent","email_blocked","mailbox_created","mailbox_deleted","outbound_consent_requested","outbound_consent_approved","outbound_consent_denied"]},"status":{"type":"string","enum":["pending","success","failed","exhausted"]},"attempts":{"type":"number"},"maxAttempts":{"type":"number"},"lastError":{"type":["null","string"]},"responseCode":{"type":["null","number"]},"payload":{},"nextRetryAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","webhookId","auditEventId","eventType","status","attempts","maxAttempts","lastError","responseCode","payload","nextRetryAt","createdAt"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/policies/outbound":{"get":{"operationId":"getApiPoliciesOutbound","tags":["outbound-policy"],"description":"Get the active organization's outbound policy.","security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"bearerAuth":[]},{"organizationApiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"mute":{"type":"boolean"},"enableWhitelist":{"type":"boolean"},"enableReplyWindow":{"type":"boolean"},"replyWindowHours":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"effectiveEnableWhitelist":{"type":"boolean"},"effectiveEnableReplyWindow":{"type":"boolean"},"planAllowsWhitelist":{"type":"boolean"},"planAllowsReplyWindow":{"type":"boolean"}},"required":["id","organizationId","mute","enableWhitelist","enableReplyWindow","replyWindowHours","createdAt","updatedAt","effectiveEnableWhitelist","effectiveEnableReplyWindow","planAllowsWhitelist","planAllowsReplyWindow"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"patch":{"operationId":"patchApiPoliciesOutbound","tags":["outbound-policy"],"description":"Update the active organization's outbound policy.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mute":{"type":"boolean"},"enableWhitelist":{"type":"boolean"},"enableReplyWindow":{"type":"boolean"},"replyWindowHours":{"type":"integer","minimum":1,"maximum":720}},"additionalProperties":false}}}},"security":[{"bearerAuth":[]},{"organizationApiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"mute":{"type":"boolean"},"enableWhitelist":{"type":"boolean"},"enableReplyWindow":{"type":"boolean"},"replyWindowHours":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"effectiveEnableWhitelist":{"type":"boolean"},"effectiveEnableReplyWindow":{"type":"boolean"},"planAllowsWhitelist":{"type":"boolean"},"planAllowsReplyWindow":{"type":"boolean"}},"required":["id","organizationId","mute","enableWhitelist","enableReplyWindow","replyWindowHours","createdAt","updatedAt","effectiveEnableWhitelist","effectiveEnableReplyWindow","planAllowsWhitelist","planAllowsReplyWindow"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"description":"Bad request","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/policy-approvals":{"get":{"operationId":"getApiPolicyApprovals","tags":["outbound-policy"],"description":"List outbound recipient lifecycle rows for the active organization.","security":[{"bearerAuth":[]},{"organizationApiKey":[]},{"bearerAuth":[]},{"organizationApiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"email":{"type":"string","maxLength":320},"status":{"type":"string","enum":["pending","approved","denied","revoked"]},"note":{"type":["null","string"]},"requestedBy":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}]},"requestedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deniedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"isExpired":{"type":"boolean"}},"required":["id","organizationId","email","status","note","requestedBy","requestedAt","approvedAt","deniedAt","expiresAt","createdAt","updatedAt"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}},"post":{"operationId":"postApiPolicyApprovals","tags":["outbound-policy"],"description":"Request external recipient consent for the active organization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{},"note":{}},"required":["email"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]},{"organizationApiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"recipient":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"email":{"type":"string","maxLength":320},"status":{"type":"string","enum":["pending","approved","denied","revoked"]},"note":{"type":["null","string"]},"requestedBy":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}]},"requestedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deniedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"isExpired":{"type":"boolean"}},"required":["id","organizationId","email","status","note","requestedBy","requestedAt","approvedAt","deniedAt","expiresAt","createdAt","updatedAt"],"additionalProperties":false},"result":{"type":"string","enum":["created","already_pending","already_approved"]}},"required":["recipient","result"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"description":"Bad request","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/policy-approvals/{id}":{"delete":{"operationId":"deleteApiPolicyApprovalsById","tags":["outbound-policy"],"description":"Dismiss an outbound recipient row.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]},{"organizationApiKey":[]}],"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/policy-approvals/{id}/revoke":{"post":{"operationId":"postApiPolicyApprovalsByIdRevoke","tags":["outbound-policy"],"description":"Revoke an approved outbound recipient.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]},{"organizationApiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"organizationId":{"type":"string","maxLength":36},"email":{"type":"string","maxLength":320},"status":{"type":"string","enum":["pending","approved","denied","revoked"]},"note":{"type":["null","string"]},"requestedBy":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}]},"requestedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deniedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"isExpired":{"type":"boolean"}},"required":["id","organizationId","email","status","note","requestedBy","requestedAt","approvedAt","deniedAt","expiresAt","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/policy-approvals/consent/lookup":{"post":{"operationId":"postApiPolicyApprovalsConsentLookup","tags":["outbound-policy"],"description":"Look up safe recipient-consent request details by token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":32,"maxLength":256}},"required":["token"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"organizationName":{"type":"string"},"email":{"type":"string"},"note":{"type":["null","string"]},"status":{"type":"string","enum":["pending","approved","denied","revoked"]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"isExpired":{"type":"boolean"}},"required":["organizationName","email","note","status","expiresAt","isExpired"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"description":"Bad request","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/api/policy-approvals/consent/decide":{"post":{"operationId":"postApiPolicyApprovalsConsentDecide","tags":["outbound-policy"],"description":"Approve or deny a recipient-consent request by token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":32,"maxLength":256},"decision":{"type":"string","enum":["approve","deny"]}},"required":["token","decision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"organizationName":{"type":"string"},"email":{"type":"string"},"note":{"type":["null","string"]},"status":{"type":"string","enum":["pending","approved","denied","revoked"]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"isExpired":{"type":"boolean"}},"required":["organizationName","email","note","status","expiresAt","isExpired"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"description":"Bad request","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}}},"servers":[{"url":"http://localhost:3000","description":"Development"},{"url":"https://api.broodnet.com","description":"Production"}],"tags":[{"name":"health","description":"Health and readiness checks"},{"name":"plans","description":"Endpoints related to subscription plans, pricing, and features"},{"name":"mailboxes","description":"Mailbox management and agent authentication"},{"name":"outbound-policy","description":"Outbound policy and recipient consent management"}],"externalDocs":{"url":"https://docs.broodnet.com","description":"Broodnet developer documentation"}}