{"openapi":"3.1.0","info":{"title":"AgentInbox API","version":"0.1.0","description":"Email verification infrastructure for AI agents and test automation.","contact":{"name":"AgentInbox","url":"https://agentinbox.in"}},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"tags":[{"name":"Inboxes","description":"Temporary email inbox management"},{"name":"Messages","description":"Email message retrieval"},{"name":"Extractions","description":"OTP and link extraction"},{"name":"Waits","description":"Async wait operations"},{"name":"Webhooks","description":"Webhook configuration"},{"name":"Workflows","description":"Compound operations"},{"name":"Sessions","description":"Group inboxes and waits for execution replay"},{"name":"API Keys","description":"API key management"},{"name":"Usage","description":"Daily usage and plan limits"}],"paths":{"/inboxes":{"get":{"tags":["Inboxes"],"operationId":"listInboxes","summary":"List inboxes","parameters":[{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Items per page"},{"name":"status","in":"query","schema":{"enum":["active","completed","expired"]},"description":"Filter by status"}],"responses":{"200":{"description":"List of inboxes","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["inbox"]},"emailAddress":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","expired","deleted","completed"]},"purpose":{"type":"string","nullable":true},"ttlSeconds":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","emailAddress","status","ttlSeconds","expiresAt","createdAt"]}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}},"required":["object","data","hasMore"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}},"post":{"tags":["Inboxes"],"operationId":"createInbox","summary":"Create inbox","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Idempotency key for replay protection"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ttlSeconds":{"type":"integer","minimum":300,"maximum":86400,"default":900,"description":"Inbox lifetime in seconds"},"purpose":{"type":"string","maxLength":200,"description":"Human-readable purpose"},"sessionId":{"type":"string","format":"uuid","description":"Optional session to associate this inbox with"}}}}}},"responses":{"201":{"description":"Created inbox","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["inbox"]},"emailAddress":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","expired","deleted","completed"]},"purpose":{"type":"string","nullable":true},"ttlSeconds":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","emailAddress","status","ttlSeconds","expiresAt","createdAt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited or quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/inboxes/{id}":{"get":{"tags":["Inboxes"],"operationId":"getInbox","summary":"Get inbox","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Inbox ID"}],"responses":{"200":{"description":"Inbox","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["inbox"]},"emailAddress":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","expired","deleted","completed"]},"purpose":{"type":"string","nullable":true},"ttlSeconds":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","emailAddress","status","ttlSeconds","expiresAt","createdAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}},"delete":{"tags":["Inboxes"],"operationId":"deleteInbox","summary":"Delete inbox","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Inbox ID"}],"responses":{"200":{"description":"Deleted marker","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/inboxes/{id}/messages":{"get":{"tags":["Messages"],"operationId":"listMessages","summary":"List inbox messages","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Inbox ID"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page"}],"responses":{"200":{"description":"Message summaries","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["message"]},"inboxId":{"type":"string","format":"uuid"},"fromEmail":{"type":"string","format":"email","nullable":true},"fromName":{"type":"string","nullable":true},"toEmail":{"type":"string","format":"email","nullable":true},"subject":{"type":"string","nullable":true},"hasAttachments":{"type":"boolean"},"sizeBytes":{"type":"integer","nullable":true},"receivedAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","hasAttachments","receivedAt"]}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}},"required":["object","data","hasMore"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/inboxes/{id}/extractions":{"get":{"tags":["Extractions"],"operationId":"listInboxExtractions","summary":"List inbox extractions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Inbox ID"}],"responses":{"200":{"description":"Extraction list","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["extraction"]},"inboxId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["otp","magic_link","verification_link","password_reset_link","invite_link","invoice_number","tracking_number","api_token","coupon_code"]},"value":{"type":"string","nullable":true},"url":{"type":"string","format":"uri","nullable":true},"confidence":{"type":"number","minimum":0,"maximum":1,"nullable":true},"candidates":{"type":"array","items":{"type":"object"},"nullable":true},"source":{"type":"string","enum":["text","html","subject"],"nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","messageId","type","createdAt"]}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}},"required":["object","data","hasMore"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/messages/{id}":{"get":{"tags":["Messages"],"operationId":"getMessage","summary":"Get message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Message ID"}],"responses":{"200":{"description":"Message with sanitized HTML body","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["message"]},"inboxId":{"type":"string","format":"uuid"},"fromEmail":{"type":"string","format":"email","nullable":true},"fromName":{"type":"string","nullable":true},"toEmail":{"type":"string","format":"email","nullable":true},"subject":{"type":"string","nullable":true},"hasAttachments":{"type":"boolean"},"sizeBytes":{"type":"integer","nullable":true},"receivedAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","hasAttachments","receivedAt"]},{"type":"object","properties":{"textBody":{"type":"string","nullable":true},"htmlBody":{"type":"string","nullable":true}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/messages/{id}/extract":{"post":{"tags":["Extractions"],"operationId":"extractMessage","summary":"Re-run extraction for a message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Message ID"},{"name":"useLlm","in":"query","schema":{"type":"boolean","default":false},"description":"Use LLM fallback for extraction"}],"responses":{"200":{"description":"Extraction list","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["extraction"]},"inboxId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["otp","magic_link","verification_link","password_reset_link","invite_link","invoice_number","tracking_number","api_token","coupon_code"]},"value":{"type":"string","nullable":true},"url":{"type":"string","format":"uri","nullable":true},"confidence":{"type":"number","minimum":0,"maximum":1,"nullable":true},"candidates":{"type":"array","items":{"type":"object"},"nullable":true},"source":{"type":"string","enum":["text","html","subject"],"nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","messageId","type","createdAt"]}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}},"required":["object","data","hasMore"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/waits":{"post":{"tags":["Waits"],"operationId":"createWait","summary":"Create wait resource","parameters":[{"name":"wait","in":"query","schema":{"type":"boolean","default":false},"description":"Long-poll up to ~50s when true."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inboxId","type"],"properties":{"inboxId":{"type":"string","format":"uuid","description":"Inbox to wait on"},"type":{"type":"string","enum":["email","otp","magic_link","password_reset"],"description":"What to wait for"},"timeoutSeconds":{"type":"integer","minimum":1,"maximum":300,"default":60,"description":"Wait timeout in seconds"},"filters":{"type":"object","properties":{"from":{"type":"string","format":"email","description":"Filter by sender email"},"subjectContains":{"type":"string","maxLength":200,"description":"Filter by subject text"},"since":{"type":"string","format":"date-time","description":"Only messages after this time"}}}}}}}},"responses":{"201":{"description":"Wait","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["wait"]},"inboxId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string","enum":["email","otp","magic_link","password_reset"]},"status":{"type":"string","enum":["pending","completed","timeout","cancelled"]},"timeoutSeconds":{"type":"integer"},"filters":{"type":"object","nullable":true},"result":{"type":"object","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","type","status","timeoutSeconds","expiresAt","createdAt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited or quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/waits/{id}":{"get":{"tags":["Waits"],"operationId":"getWait","summary":"Get wait","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Wait ID"}],"responses":{"200":{"description":"Wait","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["wait"]},"inboxId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string","enum":["email","otp","magic_link","password_reset"]},"status":{"type":"string","enum":["pending","completed","timeout","cancelled"]},"timeoutSeconds":{"type":"integer"},"filters":{"type":"object","nullable":true},"result":{"type":"object","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","type","status","timeoutSeconds","expiresAt","createdAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/waits/{id}/cancel":{"post":{"tags":["Waits"],"operationId":"cancelWait","summary":"Cancel wait","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Wait ID"}],"responses":{"200":{"description":"Wait","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["wait"]},"inboxId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string","enum":["email","otp","magic_link","password_reset"]},"status":{"type":"string","enum":["pending","completed","timeout","cancelled"]},"timeoutSeconds":{"type":"integer"},"filters":{"type":"object","nullable":true},"result":{"type":"object","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","type","status","timeoutSeconds","expiresAt","createdAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/waits/{id}/stream":{"get":{"tags":["Waits"],"operationId":"streamWait","summary":"Stream wait completion events over SSE","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Wait ID"}],"responses":{"200":{"description":"text/event-stream wait updates","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/workflow/create-inbox-and-wait":{"post":{"tags":["Workflows"],"operationId":"createInboxAndWait","summary":"Create inbox and wait in one request","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ttlSeconds":{"type":"integer","minimum":300,"maximum":86400,"default":900},"purpose":{"type":"string","maxLength":200},"waitType":{"type":"string","enum":["email","otp","magic_link","password_reset"]},"timeoutSeconds":{"type":"integer","minimum":1,"maximum":300,"default":60},"filters":{"type":"object","properties":{"from":{"type":"string","format":"email"},"subjectContains":{"type":"string","maxLength":200},"since":{"type":"string","format":"date-time"}}}}}}}},"responses":{"201":{"description":"Inbox and wait created","content":{"application/json":{"schema":{"type":"object","properties":{"inbox":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["inbox"]},"emailAddress":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","expired","deleted","completed"]},"purpose":{"type":"string","nullable":true},"ttlSeconds":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","emailAddress","status","ttlSeconds","expiresAt","createdAt"]},"wait":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["wait"]},"inboxId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string","enum":["email","otp","magic_link","password_reset"]},"status":{"type":"string","enum":["pending","completed","timeout","cancelled"]},"timeoutSeconds":{"type":"integer"},"filters":{"type":"object","nullable":true},"result":{"type":"object","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","type","status","timeoutSeconds","expiresAt","createdAt"]}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited or quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/workflow/signup":{"post":{"tags":["Workflows"],"operationId":"signupWorkflow","summary":"Signup workflow — create inbox + wait for verification","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"serviceName":{"type":"string","description":"Name of the service being tested"},"waitType":{"type":"string","enum":["otp","magic_link","password_reset"],"default":"otp"},"timeoutSeconds":{"type":"integer","minimum":1,"maximum":300,"default":120}}}}}},"responses":{"201":{"description":"Signup workflow created","content":{"application/json":{"schema":{"type":"object","properties":{"inbox":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["inbox"]},"emailAddress":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","expired","deleted","completed"]},"purpose":{"type":"string","nullable":true},"ttlSeconds":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","emailAddress","status","ttlSeconds","expiresAt","createdAt"]},"wait":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["wait"]},"inboxId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string","enum":["email","otp","magic_link","password_reset"]},"status":{"type":"string","enum":["pending","completed","timeout","cancelled"]},"timeoutSeconds":{"type":"integer"},"filters":{"type":"object","nullable":true},"result":{"type":"object","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","type","status","timeoutSeconds","expiresAt","createdAt"]},"instructions":{"type":"object","properties":{"emailAddress":{"type":"string","format":"email"},"useThisEmail":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited or quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/webhooks":{"get":{"tags":["Webhooks"],"operationId":"listWebhooks","summary":"List webhooks","responses":{"200":{"description":"Webhook list","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["webhook"]},"name":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","object","name","endpointUrl","events","active","createdAt","updatedAt"]}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}},"required":["object","data","hasMore"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}},"post":{"tags":["Webhooks"],"operationId":"createWebhook","summary":"Create webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","endpointUrl","events"],"properties":{"name":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Webhook plus secret shown once","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["webhook"]},"name":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","object","name","endpointUrl","events","active","createdAt","updatedAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited or quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/webhooks/{id}":{"get":{"tags":["Webhooks"],"operationId":"getWebhook","summary":"Get webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["webhook"]},"name":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","object","name","endpointUrl","events","active","createdAt","updatedAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}},"patch":{"tags":["Webhooks"],"operationId":"updateWebhook","summary":"Update webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["webhook"]},"name":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","object","name","endpointUrl","events","active","createdAt","updatedAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}},"delete":{"tags":["Webhooks"],"operationId":"deleteWebhook","summary":"Delete webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted marker","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/webhooks/{id}/test":{"post":{"tags":["Webhooks"],"operationId":"testWebhook","summary":"Send test webhook event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Delivery","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/webhooks/{id}/rotate-secret":{"post":{"tags":["Webhooks"],"operationId":"rotateWebhookSecret","summary":"Rotate webhook signing secret","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook plus new secret shown once","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["webhook"]},"name":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","object","name","endpointUrl","events","active","createdAt","updatedAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/webhook-deliveries/{id}/redeliver":{"post":{"tags":["Webhooks"],"operationId":"redeliverWebhook","summary":"Redeliver a webhook delivery","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Re-attempted delivery","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/sessions":{"get":{"tags":["Sessions"],"operationId":"listSessions","summary":"List sessions","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Items per page"}],"responses":{"200":{"description":"Session list","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["session"]},"name":{"type":"string"},"status":{"type":"string","enum":["active","completed","expired"]},"metadata":{"type":"object","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","object","name","status","createdAt","updatedAt"]}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}},"required":["object","data","hasMore"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}},"post":{"tags":["Sessions"],"operationId":"createSession","summary":"Create session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"ttlSeconds":{"type":"integer","minimum":300,"maximum":86400,"default":3600},"metadata":{"type":"object","description":"Arbitrary JSON metadata"}}}}}},"responses":{"201":{"description":"Created session","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["session"]},"name":{"type":"string"},"status":{"type":"string","enum":["active","completed","expired"]},"metadata":{"type":"object","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","object","name","status","createdAt","updatedAt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/sessions/{id}":{"get":{"tags":["Sessions"],"operationId":"getSession","summary":"Get session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Session ID"},{"name":"include","in":"query","schema":{"type":"string"},"description":"Comma-separated related resources: inboxes,waits,messages,extractions,timeline"}],"responses":{"200":{"description":"Session","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["session"]},"name":{"type":"string"},"status":{"type":"string","enum":["active","completed","expired"]},"metadata":{"type":"object","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","object","name","status","createdAt","updatedAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}},"post":{"tags":["Sessions"],"operationId":"completeSession","summary":"Complete a session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Session ID"}],"responses":{"200":{"description":"Updated session","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["session"]},"name":{"type":"string"},"status":{"type":"string","enum":["active","completed","expired"]},"metadata":{"type":"object","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","object","name","status","createdAt","updatedAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api-keys":{"get":{"tags":["API Keys"],"operationId":"listApiKeys","summary":"List API keys","responses":{"200":{"description":"API key list","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["api_key"]},"name":{"type":"string","nullable":true},"keyPrefix":{"type":"string"},"environment":{"type":"string","enum":["live","test"]},"scopes":{"type":"array","items":{"type":"string"}},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","keyPrefix","environment","scopes","createdAt"]}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}},"required":["object","data","hasMore"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}},"post":{"tags":["API Keys"],"operationId":"createApiKey","summary":"Create API key (plaintext key returned once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["environment"],"properties":{"name":{"type":"string","maxLength":100},"environment":{"type":"string","enum":["live"]},"scope":{"type":"string","description":"Scope template: full_access, inboxes_only, read_only, webhooks_only, api_keys_only"}}}}}},"responses":{"201":{"description":"Created API key with one-time plaintext key","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["api_key"]},"name":{"type":"string","nullable":true},"keyPrefix":{"type":"string"},"environment":{"type":"string","enum":["live","test"]},"scopes":{"type":"array","items":{"type":"string"}},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","keyPrefix","environment","scopes","createdAt"]},{"type":"object","properties":{"key":{"type":"string"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Cannot grant broader scopes","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"API key quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api-keys/{id}":{"delete":{"tags":["API Keys"],"operationId":"deleteApiKey","summary":"Revoke and delete an API key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"API key ID"}],"responses":{"200":{"description":"Deleted marker","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/usage":{"get":{"tags":["Usage"],"operationId":"getUsage","summary":"Get current daily usage and plan limits","responses":{"200":{"description":"Usage summary","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["usage"]},"plan":{"type":"string","enum":["free","plus","scale"]},"retentionDays":{"type":"integer"},"webhooks":{"type":"boolean"},"mcp":{"type":"boolean"},"customDomains":{"type":"integer"},"metrics":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string","enum":["inboxes_created","emails_received","api_requests","waits","llm_extractions"]},"count":{"type":"integer"},"limit":{"type":"integer"},"remaining":{"type":"integer"}},"required":["metric","count","limit","remaining"]}},"resetAt":{"type":"string","format":"date-time"}},"required":["object","plan","metrics","resetAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}}}}}}}},"components":{"schemas":{"Inbox":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["inbox"]},"emailAddress":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","expired","deleted","completed"]},"purpose":{"type":"string","nullable":true},"ttlSeconds":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","emailAddress","status","ttlSeconds","expiresAt","createdAt"]},"Message":{"allOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["message"]},"inboxId":{"type":"string","format":"uuid"},"fromEmail":{"type":"string","format":"email","nullable":true},"fromName":{"type":"string","nullable":true},"toEmail":{"type":"string","format":"email","nullable":true},"subject":{"type":"string","nullable":true},"hasAttachments":{"type":"boolean"},"sizeBytes":{"type":"integer","nullable":true},"receivedAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","hasAttachments","receivedAt"]},{"type":"object","properties":{"textBody":{"type":"string","nullable":true},"htmlBody":{"type":"string","nullable":true}}}]},"MessageSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["message"]},"inboxId":{"type":"string","format":"uuid"},"fromEmail":{"type":"string","format":"email","nullable":true},"fromName":{"type":"string","nullable":true},"toEmail":{"type":"string","format":"email","nullable":true},"subject":{"type":"string","nullable":true},"hasAttachments":{"type":"boolean"},"sizeBytes":{"type":"integer","nullable":true},"receivedAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","hasAttachments","receivedAt"]},"Extraction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["extraction"]},"inboxId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["otp","magic_link","verification_link","password_reset_link","invite_link","invoice_number","tracking_number","api_token","coupon_code"]},"value":{"type":"string","nullable":true},"url":{"type":"string","format":"uri","nullable":true},"confidence":{"type":"number","minimum":0,"maximum":1,"nullable":true},"candidates":{"type":"array","items":{"type":"object"},"nullable":true},"source":{"type":"string","enum":["text","html","subject"],"nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","messageId","type","createdAt"]},"Wait":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["wait"]},"inboxId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string","enum":["email","otp","magic_link","password_reset"]},"status":{"type":"string","enum":["pending","completed","timeout","cancelled"]},"timeoutSeconds":{"type":"integer"},"filters":{"type":"object","nullable":true},"result":{"type":"object","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","inboxId","type","status","timeoutSeconds","expiresAt","createdAt"]},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["webhook"]},"name":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","object","name","endpointUrl","events","active","createdAt","updatedAt"]},"Session":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["session"]},"name":{"type":"string"},"status":{"type":"string","enum":["active","completed","expired"]},"metadata":{"type":"object","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","object","name","status","createdAt","updatedAt"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["api_key"]},"name":{"type":"string","nullable":true},"keyPrefix":{"type":"string"},"environment":{"type":"string","enum":["live","test"]},"scopes":{"type":"array","items":{"type":"string"}},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","keyPrefix","environment","scopes","createdAt"]},"Usage":{"type":"object","properties":{"object":{"type":"string","enum":["usage"]},"plan":{"type":"string","enum":["free","plus","scale"]},"retentionDays":{"type":"integer"},"webhooks":{"type":"boolean"},"mcp":{"type":"boolean"},"customDomains":{"type":"integer"},"metrics":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string","enum":["inboxes_created","emails_received","api_requests","waits","llm_extractions"]},"count":{"type":"integer"},"limit":{"type":"integer"},"remaining":{"type":"integer"}},"required":["metric","count","limit","remaining"]}},"resetAt":{"type":"string","format":"date-time"}},"required":["object","plan","metrics","resetAt"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","quota_exceeded","conflict","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message"]}},"required":["error"]}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token (API key)"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key in header"}}}}