{"openapi":"3.1.0","info":{"title":"Email Watch agent API","version":"1.0.0","description":"HTTP API for an AI agent acting on one Email Watch account. Send the agent key as Authorization: Bearer ewa_.... Read keys can list domains and read health, reports, and issues. Mutate keys can also add and update domains. Add and update accept dryRun, and the MCP tools send dryRun true unless the caller sets it false. Domain routes are the contract in docs/agent-mcp.md."},"servers":[{"url":"https://app.emailwatch.co"}],"security":[{"agentBearer":[]}],"components":{"securitySchemes":{"agentBearer":{"type":"http","scheme":"bearer","bearerFormat":"ewa","description":"Agent key created in Settings. Shown once. Prefix ewa_."}},"responses":{"Unauthorized":{"description":"Missing, malformed, unknown, revoked, or closed-account token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"unauthorized"}},"required":["error"]}}}},"Forbidden":{"description":"The key is live and its permission is below the route minimum.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"forbidden"},"requiredPermission":{"type":"string","enum":["read","mutate"]}},"required":["error","requiredPermission"]}}}}}},"paths":{"/api/agent/whoami":{"get":{"operationId":"whoami","summary":"Identify the agent credential","description":"Read probe. Returns the credential id, account id, permission, and name for the bearer token.","responses":{"200":{"description":"Credential identity.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/agent/domains":{"get":{"operationId":"list_domains","summary":"List domains","description":"List domains on the authenticated Email Watch account. Read keys can call this. The response is the JSON from GET /api/agent/domains. Requires permission: read.","responses":{"200":{"description":"Handler JSON. The MCP adapter forwards this body unchanged.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size from 1 to 100. Omitted uses the handler default of 25.","schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size from 1 to 100. Omitted uses the handler default of 25."}},{"name":"offset","in":"query","required":false,"description":"Number of items to skip. Omitted starts at 0.","schema":{"type":"integer","minimum":0,"maximum":999999999,"description":"Number of items to skip. Omitted starts at 0."}}]},"post":{"operationId":"add_domain","summary":"Add a domain","description":"Add a domain to the account. Requires a mutate key. dryRun defaults to true and previews the add without saving. Set dryRun to false only after the account holder confirms. Requires permission: mutate.","responses":{"200":{"description":"Handler JSON. The MCP adapter forwards this body unchanged.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"201":{"description":"Domain created. A dry run returns 200 with a preview instead.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":255,"description":"Domain name to monitor, such as example.com."},"dryRun":{"type":"boolean","description":"When true (the default), the handler previews the change and does not save it. Set false only after the account holder confirms the preview."}},"required":["domain"],"additionalProperties":false},"example":{"domain":"example.com","dryRun":true}}}}}},"/api/agent/domains/{domainId}/health":{"get":{"operationId":"get_domain_health","summary":"Get domain health","description":"Read health for one domain (status, DMARC configuration, verification). Read keys can call this. domainId is the id from list_domains. Requires permission: read.","responses":{"200":{"description":"Handler JSON. The MCP adapter forwards this body unchanged.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"parameters":[{"name":"domainId","in":"path","required":true,"description":"Domain id from list_domains. Not the domain name.","schema":{"type":"string","minLength":1,"maxLength":64,"description":"Domain id from list_domains. Not the domain name."}}]}},"/api/agent/domains/{domainId}/reports":{"get":{"operationId":"get_domain_reports","summary":"Get domain reports","description":"Read the DMARC report list for one domain. Read keys can call this. limit and offset page the list. org matches the reporter organization name. Requires permission: read.","responses":{"200":{"description":"Handler JSON. The MCP adapter forwards this body unchanged.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"parameters":[{"name":"domainId","in":"path","required":true,"description":"Domain id from list_domains. Not the domain name.","schema":{"type":"string","minLength":1,"maxLength":64,"description":"Domain id from list_domains. Not the domain name."}},{"name":"limit","in":"query","required":false,"description":"Page size from 1 to 100. Omitted uses the handler default of 25.","schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size from 1 to 100. Omitted uses the handler default of 25."}},{"name":"offset","in":"query","required":false,"description":"Number of items to skip. Omitted starts at 0.","schema":{"type":"integer","minimum":0,"maximum":999999999,"description":"Number of items to skip. Omitted starts at 0."}},{"name":"org","in":"query","required":false,"description":"Reporter organization name. Matches the dashboard reports filter exactly.","schema":{"type":"string","minLength":1,"maxLength":255,"description":"Reporter organization name. Matches the dashboard reports filter exactly."}}]}},"/api/agent/domains/{domainId}/issues":{"get":{"operationId":"get_domain_issues","summary":"Get domain issues","description":"Read open issues for one domain. Read keys can call this. domainId is the id from list_domains. Requires permission: read.","responses":{"200":{"description":"Handler JSON. The MCP adapter forwards this body unchanged.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"parameters":[{"name":"domainId","in":"path","required":true,"description":"Domain id from list_domains. Not the domain name.","schema":{"type":"string","minLength":1,"maxLength":64,"description":"Domain id from list_domains. Not the domain name."}},{"name":"limit","in":"query","required":false,"description":"Page size from 1 to 100. Omitted uses the handler default of 25.","schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size from 1 to 100. Omitted uses the handler default of 25."}},{"name":"offset","in":"query","required":false,"description":"Number of items to skip. Omitted starts at 0.","schema":{"type":"integer","minimum":0,"maximum":999999999,"description":"Number of items to skip. Omitted starts at 0."}}]}},"/api/agent/domains/{domainId}":{"patch":{"operationId":"update_domain","summary":"Update a domain","description":"Update a domain's target DMARC policy, rua override, quoted DNS values, or whether it sends email. Requires a mutate key. dryRun defaults to true. Send at least one setting besides dryRun and reason. Requires permission: mutate.","responses":{"200":{"description":"Handler JSON. The MCP adapter forwards this body unchanged.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"parameters":[{"name":"domainId","in":"path","required":true,"description":"Domain id from list_domains. Not the domain name.","schema":{"type":"string","minLength":1,"maxLength":64,"description":"Domain id from list_domains. Not the domain name."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targetPolicy":{"type":"string","minLength":1,"maxLength":20,"description":"Target DMARC policy the account is working toward.","enum":["none","quarantine","reject"]},"reason":{"type":"string","minLength":1,"maxLength":500,"description":"Optional note stored when targetPolicy changes. Max 500 characters. Cannot be sent alone."},"ruaOverride":{"type":"boolean","description":"True when the account forwards aggregate reports to Email Watch from its own address."},"quoteDnsValues":{"type":"boolean","description":"The domain quoteDnsValues flag."},"sendsEmail":{"type":"boolean","description":"True when the domain sends legitimate mail. False when it is parked."},"dryRun":{"type":"boolean","description":"When true (the default), the handler previews the change and does not save it. Set false only after the account holder confirms the preview."}},"required":[],"additionalProperties":false},"example":{"targetPolicy":"quarantine","dryRun":true}}}}}}}}