{"openapi":"3.0.4","info":{"title":"Kenso API: Domains","version":"1.1","description":"The Domains endpoints of the Kenso API, with every component they use. The full spec is https://api.ken.so/v1/docs/openapi.json. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`."},"servers":[{"url":"https://api.ken.so"}],"security":[{"Bearer":[]}],"tags":[{"name":"domains","description":"Domains are the sending domains in your workspace: the ones Kenso bought for you and the ones you imported. Use\nthese operations to read a domain's status, renewal, tracking and ramp-up settings, change them on one domain or on\nup to 1,000 at once, and check its health and DNS. Health results come from a check Kenso runs every day; start a\nfresh one with `POST /v1/domain-health-checks`.","x-displayName":"Domains"}],"paths":{"/v1/domains":{"get":{"tags":["domains"],"summary":"List domains","description":"Returns the workspace's domains, one page at a time. Each item has the same shape as\n`GET /v1/domains/{domainId}`.\n            \n`limit` is from 1 to 200 and defaults to 50. To get the next page, send the `nextCursor` of the\nprevious page as `cursor`.\n            \nErrors:\n            \n- `400 validation_failed`: `limit` is out of range, or `cursor` did not come from this list.\n            \nRequires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"domains.list","parameters":[{"name":"cursor","in":"query","description":"The `nextCursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Domains per page, from 1 to 200. Default 50.","schema":{"maximum":200,"minimum":1,"type":"integer","format":"int32","default":50}},{"name":"Ken-Version","in":"header","description":"The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"view","summary":"Delivery view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/domains/{domainId}":{"get":{"tags":["domains"],"summary":"Get a domain","description":"Returns one domain with its status, registration and renewal, click tracking, ramp-up and tags.\n            \nFor a domain you imported, it also returns `nameservers`: the two nameservers to set at the domain's\nregistrar (`expected`), the ones it has now (`current`) and `status` (`pending`,\n`action_required` after 24 hours without the change, or `active`), and `registrarInfo`: the\nregistrar from public RDAP with the key of its steps (`guide`). The domain stays at its registrar; Kenso\nnever transfers it. When the nameservers already point at Kenso but setup waits for credits to pay the first\nmonth of the domain's mailboxes, `nameservers.waitingForCredits` is true, with\n`requiredMillicredits` and `availableMillicredits`. The fields mean what they mean on the nameserver\ncheck, but this read reports the wait as soon as the nameservers match, which can be before Kenso's DNS zone for\nthe domain is active; the check reports it only once the zone is active.\n            \nErrors:\n            \n- `404 not_found`: the workspace has no domain with this id.\n            \nRequires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"domains.get","parameters":[{"name":"domainId","in":"path","description":"The domain's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"view","summary":"Delivery view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"patch":{"tags":["domains"],"summary":"Update a domain","description":"Changes one domain's settings. Send only the fields you want to change: a field you leave out keeps its value.\n            \nThe body fields:\n            \n- `clickRateTrackingEnabled`: true or false. Turns click tracking through this domain on or off.\n- `rampUpDays`: a whole number from 0 to 30. Over this many days Kenso raises the daily send limit of the\ndomain's inboxes to their full limit. 0 turns ramp-up off.\n- `redirectUrl404`: the forwarding URL, where Kenso sends people who open the domain in a browser. A public\nhttp or https URL, or null to clear it. Kenso refuses a URL that fails its link reputation check.\n- `tagIds`: the domain's tags. The list replaces the current tags; an empty list or null removes them all.\n- `autoRenew`: true or false. Whether Kenso renews the domain's registration before it expires. Only a\ndomain Kenso bought can renew (`autoRenewEligible`). Changing it also needs the `billing` permission.\n- `websiteMode`: `redirect` or `page`. `redirect` keeps sending visitors to the forwarding URL;\n`page` asks Kenso to serve the workspace's outbound site page on the domain. Once set, it cannot go back to\nunset.\n            \nKenso saves the fields one after another and stops at the first field that fails. The error message then names\nthe fields already saved. A body with no fields returns the domain unchanged. Returns the updated domain.\nExample: `{ \"rampUpDays\": 21, \"tagIds\": [12] }`.\n            \nErrors:\n            \n- `400 validation_failed`: a field has a wrong value, the body has an unknown field, or a change failed.\n- `403 permission_denied`: the body changes `autoRenew` and you do not have the `billing` permission.\nNothing is written.\n- `404 not_found`: the workspace has no domain with this id, or a `tagIds` entry is not a tag of this\nworkspace. Nothing is written.\n            \nRequires Delivery edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.","operationId":"domains.update","parameters":[{"name":"domainId","in":"path","description":"The domain's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"403":{"description":"Forbidden","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["permission_denied"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}},"delete":{"tags":["domains"],"summary":"Delete a domain","description":"Removes the domain from the workspace. Kenso stops serving the redirects and tracked links on the domain.\nReturns `204` with no body.\n            \nErrors:\n            \n- `400 validation_failed`: the domain is hosted by your email provider, not by Kenso, which keeps it only to\ncheck the mailboxes connected on it.\n- `404 not_found`: the workspace has no domain with this id.\n            \nRequires Delivery edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.","operationId":"domains.delete","parameters":[{"name":"domainId","in":"path","description":"The domain's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`.","schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"No Content","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/domains/bulk-update":{"post":{"tags":["domains"],"summary":"Update many domains","description":"Applies the same changes to up to 1,000 domains in one call, such as turning click tracking on for a group of\ndomains or giving them all the same tags.\n            \nThe body is a JSON object with `ids`, a list of 1 to 1,000 domain ids, and at least one field to change.\nThe fields and their rules are the same as on `PATCH /v1/domains/{domainId}`: `clickRateTrackingEnabled`,\n`rampUpDays`, `redirectUrl404`, `tagIds`, `autoRenew` and `websiteMode`. Every domain\ngets the same values. Kenso ignores a repeated id.\n            \nKenso updates each domain on its own, so one failed domain does not stop the others. The response gives\n`updatedCount`, the number of domains updated, and one `failed` entry with the reason for each domain\nthat was not, such as an id that is not a domain of this workspace. Example:\n`{ \"ids\": [4, 9], \"rampUpDays\": 14 }`.\n            \nErrors:\n            \n- `400 validation_failed`: `ids` is missing, empty or longer than 1,000, the body has no field to change\nor an unknown field, or a field has a wrong value.\n- `403 permission_denied`: the body changes `autoRenew` and you do not have the `billing` permission.\nNothing is written.\n- `404 not_found`: a `tagIds` entry is not a tag of this workspace. Nothing is written.\n            \nRequires Delivery edit.\n\nRate limit: 480 calls a minute per API key, on top of the workspace limits.","operationId":"domains.bulk-update","parameters":[{"name":"Ken-Version","in":"header","description":"The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainBulkResultResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"403":{"description":"Forbidden","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["permission_denied"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":480,"windowSeconds":60,"per":"api_key"}}},"/v1/domains/{domainId}/health":{"get":{"tags":["domains"],"summary":"Get a domain's health","description":"Returns the latest health results for one domain: blocklist listings, mail DNS records, bounce rate, the latest\nplacement test, nameservers and the SSL certificate. Use it to find out why a domain's mail lands in spam or\nbounces.\n            \nThe blocklist, mail DNS and certificate fields come from the latest health check, dated by `checkedAt`.\nKenso runs a check every day, and you can start one with `POST /v1/domain-health-checks`. They stay the\nsame until the next check finishes, except `blocklistVerdict`: it also counts Kenso's own daily blocklist\ncheck, and stops counting a health check more than 7 days old. Rates are fractions from 0 to 1.\n            \nErrors:\n            \n- `404 not_found`: the workspace has no domain with this id.\n            \nRequires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"domains.get-health","parameters":[{"name":"domainId","in":"path","description":"The domain's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainHealthResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"view","summary":"Delivery view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/domains/health":{"get":{"tags":["domains"],"summary":"List the health of many domains","description":"Returns the latest health results for up to 200 domains in one call, such as every domain on a page. Each item\nis what `GET /v1/domains/{domainId}/health` returns for that domain, so the fields, their sources and how\nfresh they are read the same way there.\n            \n`domainIds` is required: 1 to 200 domain ids, comma-separated, such as `domainIds=4,9,12`. Items come\nin the order of `domainIds`, and Kenso ignores a repeated id. An id that is not a domain of this workspace\nhas no item, where the one-domain read answers `404`. The list has no further pages:\n`pagination.hasMore` is always false.\n            \nErrors:\n            \n- `400 validation_failed`: `domainIds` is missing, has a value that is not a positive whole number, or\nhas more than 200 ids.\n            \nRequires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"domains.list-health","parameters":[{"name":"domainIds","in":"query","description":"The domains to read: 1 to 200 domain ids, comma-separated.","schema":{"type":"string"}},{"name":"Ken-Version","in":"header","description":"The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainHealthListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"view","summary":"Delivery view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/domains/{domainId}/dns":{"get":{"tags":["domains"],"summary":"Get a domain's tracking DNS","description":"Returns the click tracking DNS state of one domain: whether its DNS points at Kenso's redirect servers, which\nclick tracking through the domain needs, and its open pixel host. Kenso rechecks the DNS on a schedule. To check\nit right away, for example after you changed a record, call `POST /v1/domains/{domainId}/verify-dns`.\n            \nErrors:\n            \n- `404 not_found`: the workspace has no domain with this id.\n            \nRequires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"domains.get-dns","parameters":[{"name":"domainId","in":"path","description":"The domain's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDnsResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"view","summary":"Delivery view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/domains/{domainId}/verify-dns":{"post":{"tags":["domains"],"summary":"Verify a domain's tracking DNS","description":"Checks now whether the domain's DNS records point at Kenso's redirect servers, saves the result and returns it in\nthe same shape as `GET /v1/domains/{domainId}/dns`. Call it after you add or change the records. The domain\nmust have click tracking on (`clickRateTrackingEnabled`).\n            \nErrors:\n            \n- `400 validation_failed`: the records do not point at Kenso yet (the message gives the reason, and\n`lastError` keeps it), click tracking is off for the domain, or the workspace has no domain with this id.\n            \nRequires Delivery edit.\n\nRate limit: 10 calls a minute per API key, on top of the workspace limits.","operationId":"domains.verify-dns","parameters":[{"name":"domainId","in":"path","description":"The domain's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDnsResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":10,"windowSeconds":60,"per":"api_key"}}},"/v1/domains/{domainId}/check-nameservers":{"post":{"tags":["domains"],"summary":"Check a domain's nameservers","description":"For a domain you imported, checks whether its nameservers now point at the DNS zone Kenso created for it in\nKenso's DNS account, and starts setting the domain up once they do. Call it after you change the\nnameservers at your registrar. `expectedNameservers` lists the nameservers to set.\n            \n`activated` turns true once the domain is set up. Until then the response says where it stands:\n`zoneStatus` is the zone's state, and `waitingForCredits` is true when setup waits for credits to pay\nthe first month of the domain's mailboxes. Add credits, then call again.\n            \nErrors:\n            \n- `400 validation_failed`: Kenso has no DNS zone for the domain.\n- `404 not_found`: the workspace has no imported domain with this id.\n- `503 service_unavailable`: Kenso could not check the zone. Try again later.\n            \nRequires Delivery edit.\n\nRate limit: 10 calls a minute per API key, on top of the workspace limits.","operationId":"domains.check-nameservers","parameters":[{"name":"domainId","in":"path","description":"The domain's id. It must be a domain you imported.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainNameserverCheckResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]},"503":{"description":"Service Unavailable","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableError"}}},"x-ken-error-codes":["service_unavailable"]}},"x-ken-permission":{"kind":"page","page":"delivery","access":"edit","summary":"Delivery edit"},"x-ken-rate-limit":{"limit":10,"windowSeconds":60,"per":"api_key"}}}},"components":{"securitySchemes":{"Bearer":{"type":"http","description":"Enter: Bearer {your Kenso API key}. Create one in the Kenso app under Settings > Integrations > API Keys.","scheme":"bearer","bearerFormat":"Opaque API key"}},"headers":{"RateLimit-Limit":{"description":"The request limit of the rate limit this request is closest to reaching: your plan's limit for this kind of call, your API key's own limit, or the operation's own limit, whichever has the fewest requests left.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The requests left under that limit. `0` on a `429`.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The seconds until that limit resets.","schema":{"type":"integer"}}},"schemas":{"ApiKeyError":{"required":["error"],"type":"object","properties":{"error":{"type":"string","description":"A sentence for people that says what went wrong. It can change, so do not parse it."}},"additionalProperties":false,"description":"The body the API key check in front of the operations answered until November 2026, instead of the error body (`Failure`): `{ \"error\": \"Invalid or revoked API key\" }` on a `401`, `{ \"error\": \"Rate limit exceeded\" }` on a `429` and `{ \"error\": \"Authentication is temporarily unavailable\" }` on a `503`. It has no `code`, so branch on the HTTP status."},"CampaignPixelHost":{"type":"object","properties":{"status":{"type":"string","description":"Which host serves the pixel. `link`: `link.{domain}` serves it. `unsub`: the domain's DNS is in\nKenso's DNS account, where Kenso creates `unsub.{domain}` itself. `none`: the domain has no host\nand Kenso cannot create one, so campaign emails from it go out without a pixel; `requiredRecord` names the\nrecord it needs.\n`unknown`: Kenso has not tried a host there yet (a domain with no inbox, or the workspace's website domain),\nor is still trying."},"hostname":{"type":"string","description":"The pixel host for `link` and `unsub`, else omitted. For `unsub` it is the host Kenso creates,\nwhich may not serve yet.","nullable":true},"requiredRecord":{"allOf":[{"$ref":"#/components/schemas/DomainDnsRecord"}],"description":"Set with `none` when the domain's DNS is outside Kenso: the CNAME record to add for `link.{domain}`.\nOnce public DNS shows it, Kenso registers the host on its own, usually within an hour. Omitted otherwise."}},"additionalProperties":false,"description":"Where campaign emails from a domain load their open tracking pixel."},"Domain":{"type":"object","properties":{"id":{"type":"integer","description":"The domain's id.","format":"int64"},"name":{"type":"string","description":"The domain name, such as `acme-mail.com`."},"status":{"type":"string","description":"The domain's state: `active`, `pending_setup` (Kenso is still setting it up), `paused`,\n`expired`, `blacklisted`, `banned` or `deleted`."},"source":{"type":"string","description":"Where the domain came from: `platform_purchased` (Kenso bought it for you) or `imported` (you brought\nit)."},"providerHosted":{"type":"boolean","description":"True when your email provider hosts the domain and Kenso does not run it: Kenso keeps the domain only to check\nthe mailboxes you connected on it. The domain list leaves it out, and it cannot be deleted. Importing the domain\nmoves it to Kenso."},"expirationDate":{"type":"string","description":"When the domain's registration expires, in UTC. Omitted when unknown.","format":"date-time","nullable":true},"daysLeft":{"type":"integer","description":"Whole days left until `expirationDate`, rounded down. Negative once the domain has expired. Omitted when the\nexpiry is unknown.","format":"int32","nullable":true},"isExpiring":{"type":"boolean","description":"True when the registration expires within the next 30 days and has not expired yet."},"autoRenew":{"type":"boolean","description":"True when Kenso renews the domain's registration before it expires."},"autoRenewEligible":{"type":"boolean","description":"True when Kenso can renew the domain, which holds for the domains Kenso bought."},"registrar":{"type":"string","description":"The registrar that holds the domain's registration. Omitted when unknown. Prefer registrarKind.","nullable":true},"registrarKind":{"type":"string","description":"Who holds the domain's registration, in neutral words: `kenso` when Kenso registered the domain, `other`\nfor any other registrar. Omitted when unknown.","nullable":true},"dnsProvider":{"type":"string","description":"The DNS host that serves the domain's records. Omitted when unknown. Prefer dnsHostKind.","nullable":true},"dnsHostKind":{"type":"string","description":"Who serves the domain's DNS records, in neutral words: `kenso` when Kenso hosts the zone, `other` for any\nother DNS host. Omitted when unknown.","nullable":true},"clickRateTrackingEnabled":{"type":"boolean","description":"True when click tracking through this domain is on."},"trackingDnsStatus":{"type":"string","description":"Whether the domain's DNS points at Kenso's redirect servers: `verified`, `unchecked` (not checked yet)\nor `dead` (several checks in a row failed). Omitted when the domain has no tracking settings.","nullable":true},"maskingEnabled":{"type":"boolean","description":"True when visitors to the domain see the forwarding URL's page while the address bar keeps the domain's name.\nRead-only: an update that sends it is refused."},"rampUpDays":{"type":"integer","description":"Over how many days Kenso raises the daily send limit of the domain's inboxes to their full limit, from 0 to 30.\n0 means no ramp-up. Omitted when not set.","format":"int32","nullable":true},"rampUp":{"allOf":[{"$ref":"#/components/schemas/DomainRampUp"}],"description":"Where the domain is in its ramp-up today. Omitted when Kenso could not read it."},"redirectUrl404":{"type":"string","description":"The forwarding URL: where Kenso sends people who open the domain in a browser. Omitted when none is set.","nullable":true},"openPixelHostname":{"type":"string","description":"The host that serves the open tracking pixel in one-to-one emails, such as replies, sent from this domain.\nOmitted when none is set.","nullable":true},"openPixelStatus":{"type":"string","description":"State of `openPixelHostname`: `none` (no host), `pending` (set but not verified yet),\n`verified` (Kenso adds the pixel through it) or `disabled`. Omitted when the domain has no tracking\nsettings.","nullable":true},"campaignPixelHost":{"allOf":[{"$ref":"#/components/schemas/CampaignPixelHost"}],"description":"Where campaign emails from this domain load their open tracking pixel. Omitted when Kenso could not read it."},"catchAllEmail":{"type":"string","description":"The address that gets mail sent to unknown addresses on the domain. Only returned by the update that set it;\nomitted otherwise.","nullable":true},"hasError":{"type":"boolean","description":"True when setting up the domain or its nameservers failed. `statusReason` says why."},"statusReason":{"type":"string","description":"Why the domain needs attention, in one short sentence. Omitted when nothing is wrong.","nullable":true},"isPrimary":{"type":"boolean","description":"True when this is one of the workspace's own domains: its email domain or a domain listed under\nSettings > Company. Members' primary inboxes sit on these domains, and an inbox's `isPrimary` follows the\nsame rule."},"tagIds":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Ids of the domain's tags. Empty when it has none."},"retirement":{"allOf":[{"$ref":"#/components/schemas/DomainRetirement"}],"description":"The window in which Kenso keeps catching replies after the domain was retired: the open window, else the last\none that ended. Omitted for a domain that was never retired."},"replacedBy":{"allOf":[{"$ref":"#/components/schemas/DomainReplacement"}],"description":"The domain Kenso bought to replace this one, for example after this one landed on a blocklist. Omitted when\nnothing replaced it."},"health":{"allOf":[{"$ref":"#/components/schemas/DomainHealthStatus"}],"description":"The domain's health: its rung on Ken's domain health ladder (`good`, `watch`,\n`throttle`, `quarantine`, `block`), why, and the next step. Shown only in a workspace where domain\nhealth is on; omitted otherwise and for a domain not rated yet."},"nameservers":{"allOf":[{"$ref":"#/components/schemas/DomainNameservers"}],"description":"For a domain you imported: the nameservers to set at its registrar, the ones it has now, and where the change\nstands. Only `GET /v1/domains/{domainId}` returns it. Omitted for a domain Kenso bought."},"registrarInfo":{"allOf":[{"$ref":"#/components/schemas/DomainRegistrar"}],"description":"For a domain you imported: its registrar, from public RDAP, with the key of that registrar's nameserver steps.\nOnly `GET /v1/domains/{domainId}` returns it. Omitted for a domain Kenso bought and when the lookup\nfailed. `registrar` above is a different field: the registrar Kenso has on file, as a name."}},"additionalProperties":false,"description":"A sending domain in the workspace."},"DomainBulkFailure":{"type":"object","properties":{"id":{"type":"integer","description":"The domain's id, as sent in `ids`.","format":"int64"},"message":{"type":"string","description":"Why the update failed for this domain."}},"additionalProperties":false,"description":"A domain that a bulk update could not change."},"DomainBulkResult":{"type":"object","properties":{"updatedCount":{"type":"integer","description":"How many domains Kenso updated without a failure.","format":"int32"},"failed":{"type":"array","items":{"$ref":"#/components/schemas/DomainBulkFailure"},"description":"One entry per domain that was not updated, with the reason. Empty when every domain was updated."}},"additionalProperties":false,"description":"The result of a bulk domain update."},"DomainBulkResultResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/DomainBulkResult"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"DomainDns":{"type":"object","properties":{"trackingStatus":{"type":"string","description":"Whether the domain's DNS points at Kenso's redirect servers: `verified`, `unchecked` (not checked yet)\nor `dead` (several checks in a row failed). Omitted when the domain has no tracking settings.","nullable":true},"clickRateTrackingEnabled":{"type":"boolean","description":"True when click tracking through this domain is on."},"openPixelHostname":{"type":"string","description":"The host that serves the open tracking pixel in one-to-one emails, such as replies, sent from this domain.\nOmitted when none is set.","nullable":true},"openPixelStatus":{"type":"string","description":"State of `openPixelHostname`: `none`, `pending`, `verified` or `disabled`. Omitted when\nthe domain has no tracking settings.","nullable":true},"lastError":{"type":"string","description":"Why the latest DNS check failed. Omitted when it passed or never ran.","nullable":true},"checkedAt":{"type":"string","description":"When Kenso last checked the DNS, in UTC. Omitted before the first check.","format":"date-time","nullable":true}},"additionalProperties":false,"description":"The click tracking DNS state of a domain."},"DomainDnsRecord":{"type":"object","properties":{"type":{"type":"string","description":"The record type, such as `CNAME`."},"name":{"type":"string","description":"The host name the record is for, such as `link.acme-mail.com`."},"value":{"type":"string","description":"The value the record points to."}},"additionalProperties":false,"description":"A DNS record to add at the domain's DNS host."},"DomainDnsResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/DomainDns"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"DomainHealth":{"type":"object","properties":{"domainId":{"type":"integer","description":"The domain's id.","format":"int64"},"name":{"type":"string","description":"The domain name, such as `acme-mail.com`."},"blacklistStatus":{"type":"string","description":"Blocklist result of the latest check: `clean`, `listed`, `delisted` or `pending_delisting`.\nOmitted before the first check.","nullable":true},"listedCount":{"type":"integer","description":"How many blocklists the domain was on at the latest check. 0 before the first check.","format":"int32"},"listedZones":{"type":"array","items":{"type":"string"},"description":"Names of the blocklists the domain was on at the latest check. Empty when it was on none."},"checkedAt":{"type":"string","description":"When the latest health check ran, in UTC. Omitted before the first check.","format":"date-time","nullable":true},"spfStatus":{"type":"string","description":"SPF result of the latest check: `pass`, `fail` or `unknown`. Omitted before the first check.","nullable":true},"dkimStatus":{"type":"string","description":"DKIM result of the latest check: `pass`, `fail` or `unknown`. Omitted before the first check.","nullable":true},"dmarcStatus":{"type":"string","description":"DMARC result of the latest check: `pass`, `fail` or `unknown`. Omitted before the first check.","nullable":true},"mxStatus":{"type":"string","description":"MX result of the latest check: `pass`, `fail` or `unknown`. Omitted before the first check.","nullable":true},"hasSpf":{"type":"boolean","description":"True when `spfStatus` is `pass`."},"hasDkim":{"type":"boolean","description":"True when `dkimStatus` is `pass`."},"hasDmarc":{"type":"boolean","description":"True when `dmarcStatus` is `pass`."},"hasMx":{"type":"boolean","description":"True when `mxStatus` is `pass`."},"isChecked":{"type":"boolean","description":"True when the latest check got a clear `pass` or `fail` for SPF, DKIM and DMARC. False before the first\ncheck and while any of the three is `unknown`."},"dkimSelector":{"type":"string","description":"The DKIM selector the latest check read, such as `google`. Omitted when the check found none.","nullable":true},"bounceRate":{"type":"number","description":"Share of the domain's emails that bounced in the latest bounce reading, as a fraction from 0 to 1. Omitted before\nthe first reading.","format":"double","nullable":true},"bounceStatus":{"type":"string","description":"The verdict of the latest bounce reading, as the mailbox host reports it. Omitted before the first reading.","nullable":true},"bounceCheckedAt":{"type":"string","description":"When Kenso last read the domain's bounces, in UTC. Omitted before the first reading.","format":"date-time","nullable":true},"bounceEmailCount":{"type":"integer","description":"How many emails the latest bounce reading counted. Omitted before the first reading.","format":"int32","nullable":true},"bouncedEmailCount":{"type":"integer","description":"How many of those emails bounced. Omitted before the first reading.","format":"int32","nullable":true},"inboxRate":{"type":"number","description":"Share of test emails that reached the inbox in the domain's latest completed placement test, as a fraction from\n0 to 1. Omitted when the domain has no completed test.","format":"double","nullable":true},"spamRate":{"type":"number","description":"Share of test emails that landed in spam in that placement test, as a fraction from 0 to 1. Omitted when the\ndomain has no completed test.","format":"double","nullable":true},"placementStatus":{"type":"string","description":"Status of that placement test. Omitted when the domain has no completed test.","nullable":true},"placementCompletedAt":{"type":"string","description":"When that placement test finished, in UTC. Omitted when the domain has no completed test.","format":"date-time","nullable":true},"infraguardStatus":{"type":"string","description":"Status of the domain's monitoring subscription with its mailbox host, such as `active`. Omitted when the\ndomain has none.","nullable":true},"nameserverStatus":{"type":"string","description":"Result of the latest nameserver check: `verified` (the nameservers are the expected ones), `not_moved`\n(the registrar's default nameservers are still in place), `moved_wrong_provider` (the domain points at\nnameservers other than the expected ones), `failed` (no nameservers found) or `lookup_failed` (the\nlookup did not finish). Omitted before a check.","nullable":true},"nameservers":{"type":"array","items":{"type":"string"},"description":"The nameservers Kenso found for the domain. Empty when none are known."},"sslStatus":{"type":"string","description":"State of the domain's SSL certificate at the latest check: `valid`, `expiring_soon`, `expired`,\n`invalid` or `unreachable`. Omitted when the check did not read it.","nullable":true},"sslExpiresAt":{"type":"string","description":"When the domain's SSL certificate expires, in UTC. Omitted when unknown.","format":"date-time","nullable":true},"ipAbuseScore":{"type":"integer","description":"Abuse score of the domain's sending IP from the latest check. Omitted when the check has none.","format":"int32","nullable":true},"blocklistVerdict":{"type":"string","description":"Whether the domain is on a blocklist, as Kenso decides it: `listed`, `clean` or `unknown`. It\ncombines Kenso's own daily blocklist check of the domain with the latest health check, by the rule Kenso's\ndeliverability alerts use to call a domain blocklisted. `listed` when the daily check lists the domain, or\nwhen the latest health check is no more than 7 days old and says listed, unless the only zones it names are\nURIBL grey (every other zone counts, URIBL black and red included). `clean` when neither lists it and the\ndaily check, or a health check no more than 7 days old, answered clean. `unknown` when neither has a current\nanswer: no daily check result, and the latest health check is missing, more than 7 days old or has no recognised\nstatus. A health check that names only URIBL grey is `clean` here even when `blacklistStatus` says\n`listed`, because Kenso does not count grey as a listing. Prefer this to `blacklistStatus` to tell\nwhether the domain is listed."},"listedSince":{"type":"string","description":"When Kenso first saw the domain listed, in UTC: the earliest of the day Kenso's daily blocklist check first saw the\nlisting (kept across gaps in that check) and the listing health check. Set only when `blocklistVerdict` is\n`listed`; omitted otherwise.","format":"date-time","nullable":true},"uriblGreyOnly":{"type":"boolean","description":"True when the latest health check, whatever its age, says listed and names only URIBL grey (a list of bulk\nsenders that Kenso does not count as a listing, so no action is needed). Like `blacklistStatus`, it\ndescribes that check; `blocklistVerdict` says whether it still counts. `blacklistStatus` and\n`listedZones` still show the check as the health check recorded it."}},"additionalProperties":false,"description":"The latest health results of one domain. Rates are fractions from 0 to 1."},"DomainHealthListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/DomainHealth"},"description":"The items on this page."},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"}],"description":"Where this page ends and how to get the next one."}},"additionalProperties":false,"description":"The body of a successful list operation: one page of results in `data`, and `pagination` to get the next\npage."},"DomainHealthResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/DomainHealth"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"DomainHealthStatus":{"type":"object","properties":{"rung":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"action":{"type":"string","nullable":true},"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time","nullable":true},"evaluatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false,"description":"A domain's health on Ken's domain health ladder, customer-facing: `rung` is `good`,\n`watch`, `throttle`, `quarantine` or `block`; `reason` is a vendor-neutral code; `message`\nand `action` are sentences to show a user (`action` omitted when there is nothing to do); `until` is the\nend of a quarantine."},"DomainListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/Domain"},"description":"The items on this page."},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"}],"description":"Where this page ends and how to get the next one."}},"additionalProperties":false,"description":"The body of a successful list operation: one page of results in `data`, and `pagination` to get the next\npage."},"DomainNameserverCheck":{"type":"object","properties":{"domainId":{"type":"integer","description":"The domain's id.","format":"int64"},"name":{"type":"string","description":"The domain name."},"status":{"type":"string","description":"Where the domain's setup stands: `settingUp`, `actionRequired` (the nameservers did not change in time;\nset them and check again), `active` or `failed`."},"zoneStatus":{"type":"string","description":"State of the domain's DNS zone in Kenso's DNS account, such as `pending` or `active`. Omitted\nwhen Kenso could not read the zone.","nullable":true},"activated":{"type":"boolean","description":"True when the domain is set up and active."},"expectedNameservers":{"type":"array","items":{"type":"string"},"description":"The nameservers to set for the domain at your registrar."},"waitingForCredits":{"type":"boolean","description":"True when the zone is active but setup waits until the workspace has the credits to pay the first month of the\ndomain's mailboxes."},"requiredMillicredits":{"type":"integer","description":"Credits the first month of the domain's mailboxes costs, in thousandths of a credit. Set only with\n`waitingForCredits`.","format":"int64","nullable":true},"availableMillicredits":{"type":"integer","description":"The workspace's credit balance, in thousandths of a credit. Set only with `waitingForCredits`.","format":"int64","nullable":true}},"additionalProperties":false,"description":"The result of a nameserver check on an imported domain."},"DomainNameserverCheckResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/DomainNameserverCheck"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"DomainNameservers":{"type":"object","properties":{"expected":{"type":"array","items":{"type":"string"},"description":"The nameservers to set at the domain's registrar: the ones Kenso's DNS assigned to the zone Kenso created for\nthe domain, lowercased and sorted."},"current":{"type":"array","items":{"type":"string"},"description":"The nameservers the domain has now, from a live DNS lookup (up to 10 minutes old), lowercased and sorted. Empty\nwhen the lookup failed."},"status":{"type":"string","description":"`pending` (Kenso is waiting for the change, or sees it and is finishing setup), `action_required` (no\nchange after 24 hours: change the nameservers at the registrar) or `active` (the domain is set up). Kenso checks every 15 minutes; call\n`POST /v1/domains/{domainId}/check-nameservers` to check now."},"waitingForCredits":{"type":"boolean","description":"True when the nameservers already point at Kenso but setup waits until the workspace has the credits to pay\nthe first month of the domain's mailboxes. Add credits; setup then continues on the next check."},"requiredMillicredits":{"type":"integer","description":"Credits the first month of the domain's mailboxes costs, in thousandths of a credit. Set only with\n`waitingForCredits`.","format":"int64","nullable":true},"availableMillicredits":{"type":"integer","description":"The workspace's credit balance, in thousandths of a credit. Set only with `waitingForCredits`.","format":"int64","nullable":true}},"additionalProperties":false,"description":"Where an imported domain's nameserver change stands."},"DomainRampUp":{"type":"object","properties":{"days":{"type":"integer","description":"Length of the ramp-up in days. 0 means the domain does not ramp up.","format":"int32"},"dayIndex":{"type":"integer","description":"Today's day of the ramp-up, from 1 to `days`, counted in UTC calendar days from the day it started (1 before\nit starts). Stays at `days` once the ramp-up is over, and is 0 when `days` is 0.","format":"int32"},"isComplete":{"type":"boolean","description":"True when the domain's inboxes send at their full daily limit: the ramp-up is over, the domain has none, or\nramp-up is turned off."}},"additionalProperties":false,"description":"A domain's progress through its ramp-up."},"DomainRegistrar":{"type":"object","properties":{"name":{"type":"string","description":"The registrar's name as RDAP gives it, such as `GoDaddy.com, LLC`."},"ianaId":{"type":"integer","description":"The registrar's IANA Registrar ID, such as `146`. Null when RDAP does not give one.","format":"int32","nullable":true},"guide":{"type":"string","description":"The key of that registrar's nameserver steps: `godaddy`, `namecheap`, `porkbun`,\n`cloudflare`, `squarespace`, `google`, `ionos`, `ovh`, `gandi`, `hover`,\n`namecom`, `dynadot`, `enom`, `networksolutions` or `other`."}},"additionalProperties":false,"description":"A domain's registrar, from public RDAP."},"DomainReplacement":{"type":"object","properties":{"id":{"type":"integer","description":"The replacement domain's id.","format":"int64"},"name":{"type":"string","description":"The replacement domain's name."}},"additionalProperties":false,"description":"A domain that Kenso bought to replace another."},"DomainResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/Domain"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"DomainRetirement":{"type":"object","properties":{"state":{"type":"string","description":"The window's state: `pending` (the window is opening; Kenso retries every 15 minutes until the DNS change is\nconfirmed), `applied` (Kenso receives the replies), `release_pending` (the window is closing),\n`released` (closed) or `failed` (closed without ever applying, because the domain's DNS left Kenso's\nDNS account)."},"captureUntil":{"type":"string","description":"When the capture window ends, in UTC.","format":"date-time"},"releasedAt":{"type":"string","description":"When the window ended, in UTC. Omitted while it is open.","format":"date-time","nullable":true},"renewalEndsWindowEarly":{"type":"boolean","description":"True while the window is open, auto-renew is off and the registration expires before `captureUntil`. The\ndomain can then lapse, and a new owner would get the replies."}},"additionalProperties":false,"description":"The reply capture window of a retired domain. Until `captureUntil`, Kenso receives the domain's mail, so\nreplies to emails sent from it still arrive."},"ErrorAccount":{"type":"object","properties":{"accountId":{"type":"integer","description":"The account's id.","format":"int64"},"name":{"type":"string","description":"The account's name."},"stakeholderId":{"type":"integer","description":"The person's stakeholder id on this account.","format":"int64"}},"additionalProperties":false,"description":"An account named in an error detail."},"ErrorBody":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code, such as `validation_failed` or `not_found`. Branch on this value."},"message":{"type":"string","description":"A sentence for people that explains the error. It can change, so do not parse it."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"},"description":"One entry per problem, naming the field or limit it is about. Omitted when there are none.","nullable":true},"requestId":{"type":"string","description":"The id of this request: the same value as the `X-Correlation-Id` response header. Quote it when you write\nto contact@ken.so."},"docUrl":{"type":"string","description":"The page on this code in the developer docs, which says what it means and how to fix it. The errors guide for a\ncode that has no page of its own.","readOnly":true},"refusal":{"allOf":[{"$ref":"#/components/schemas/Refusal"}],"description":"On a `402`, the plan rule or usage limit that refused the request and how to lift it. Omitted otherwise."},"impact":{"allOf":[{"$ref":"#/components/schemas/InvalidationImpact"}],"description":"On a `409` that refuses a change because it would clear stored AI output (a prompt edit, a restore or a\nreset), how much the change would clear. Omitted otherwise."},"surface":{"type":"string","description":"Set only by the voice ticket's `409` (code `voice_conversation_active`): the chat the person's other\nvoice conversation runs in, `support`, `ken` or `onboarding`. Omitted on every other error.","nullable":true}},"additionalProperties":false,"description":"What went wrong in a request."},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","description":"The request field, header or limit the problem is about, such as `name` or `Ken-Version`."},"code":{"type":"string","description":"Stable code for this problem, such as `required` or `invalid`."},"message":{"type":"string","description":"A sentence for people that explains this problem."},"count":{"type":"integer","description":"On `export_limit_exceeded`, how many rows match the export. Omitted otherwise.","format":"int32","nullable":true},"index":{"type":"integer","description":"The position of the refused item in the request's list. Omitted otherwise.","format":"int32","nullable":true},"limit":{"type":"integer","description":"On `export_limit_exceeded`, the row limit the export ran with. On a `quota_exceeded` detail whose\n`field` names a quota, that quota's limit. On a `rate_limited` detail from your workspace's rate\nlimits, the limit that was hit. Omitted otherwise.","format":"int32","nullable":true},"resetAt":{"type":"string","description":"On some `quota_exceeded` details, when the quota frees up, in UTC. It is the same instant as the top-level\n`quotaResetAt`. On a `rate_limited` detail from your workspace's rate limits, when that limit resets.\nOmitted otherwise.","format":"date-time","nullable":true},"retryAfterSeconds":{"type":"integer","description":"On those `quota_exceeded` details and on most `rate_limited` details, the seconds to wait. It is the\nsame value as the `Retry-After` header. Omitted otherwise.","format":"int32","nullable":true},"inboxId":{"type":"integer","description":"The inbox the problem is about. Omitted otherwise.","format":"int64","nullable":true},"domainId":{"type":"integer","description":"The domain the problem is about. Omitted otherwise.","format":"int64","nullable":true},"domainName":{"type":"string","description":"The name of that domain, or the domain name the request gave. Omitted otherwise.","nullable":true},"accountId":{"type":"integer","description":"On `domain_taken`, `already_stakeholder` and `previously_removed`, the existing account to use\ninstead. Omitted otherwise.","format":"int64","nullable":true},"personId":{"type":"integer","description":"On `email_taken` and `linkedin_url_taken`, the existing person to use instead. Omitted otherwise.","format":"int64","nullable":true},"stakeholderId":{"type":"integer","description":"The account stakeholder the problem is about. Omitted otherwise.","format":"int64","nullable":true},"championId":{"type":"integer","description":"Not used. Always omitted.","format":"int64","nullable":true},"callTaskId":{"type":"integer","description":"On `call_task_exists`, the open call task that already holds the person's slot. Omitted otherwise.","format":"int64","nullable":true},"status":{"type":"string","description":"On `invalid_transition`, the current status. Omitted otherwise.","nullable":true},"allowed":{"type":"array","items":{"type":"string"},"description":"On `out_of_range`, the allowed values. On `invalid_transition`, the statuses the change is allowed\nfrom. Omitted otherwise.","nullable":true},"scope":{"type":"string","description":"On a `permission_denied` for an account owner change, the account scope the call needs (`all`). On\n`sending_paused`, what the pause covers: `inbox`, `domain` or `workspace`. Omitted otherwise.","nullable":true},"removedAt":{"type":"string","description":"On `previously_removed`, when a person removed the stakeholder, in UTC. Omitted otherwise.","format":"date-time","nullable":true},"page":{"type":"string","description":"On `permission_denied`, the page the call needs, such as `campaigns`. Omitted otherwise.","nullable":true},"required":{"type":"string","description":"On `permission_denied`, the access `page` needs: `view` or `edit`. Omitted otherwise.","nullable":true},"feature":{"type":"string","description":"On `permission_denied`, the permission the call needs, such as `launch`. Omitted otherwise.","nullable":true},"runId":{"type":"integer","description":"On `committee_run_active` and `run_not_finding`, the committee run the problem is about. Omitted\notherwise.","format":"int64","nullable":true},"mergedIntoId":{"type":"integer","description":"On `person_merged`, the person the merged person now lives on. On `account_merged`, the account the\nmerged account now lives on. Omitted otherwise.","format":"int64","nullable":true},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ErrorAccount"},"description":"On `person_on_accounts`, the accounts that block the change. Omitted otherwise.","nullable":true},"stage":{"type":"string","description":"On `stage_in_use` and `system_stage`, the opportunity stage key the problem is about. Omitted otherwise.","nullable":true},"opportunityCount":{"type":"integer","description":"On `stage_in_use`, how many opportunities are in that stage. Omitted otherwise.","format":"int32","nullable":true},"rule":{"type":"string","description":"On `guardrail_violation`, the contact limit rule the change breaks. Omitted otherwise.","nullable":true},"nextAllowedAt":{"type":"string","description":"On `guardrail_violation`, the first `dueAt` that passes every contact limit, in UTC. On a refused\nsend, when to retry. Omitted otherwise, and when waiting does not clear it.","format":"date-time","nullable":true},"fix":{"type":"string","description":"On a refused send, what to do next, in plain words. Omitted otherwise.","nullable":true},"opensAt":{"type":"string","description":"On `outside_calling_hours`, when the person's calling window opens, in UTC. Omitted otherwise.","format":"date-time","nullable":true},"currentVersion":{"type":"integer","description":"On a knowledge file's `version_conflict`, the file's current version. Omitted otherwise.","format":"int32","nullable":true},"provider":{"type":"string","description":"On a CRM connection error (`provider_error`, `exchange_failed`, `already_connected`,\n`account_mismatch` or `provider_unavailable`), the CRM it is about. Omitted otherwise.","nullable":true},"sharedWithMaster":{"type":"boolean","description":"True on a `quota_exceeded` detail when the shared limit of the white-label master workspace was hit, so\n`limit` is the limit of the whole white-label account. Omitted otherwise. The master's id is never sent.","nullable":true},"stepId":{"type":"integer","description":"On `link_reputation_blocked`, the saved sequence step that holds the blocked link. Omitted otherwise, and\nfor a step the save would have created.","format":"int64","nullable":true},"stepOrder":{"type":"integer","description":"On `link_reputation_blocked`, the `stepOrder` of that step. Omitted otherwise.","format":"int32","nullable":true},"url":{"type":"string","description":"On `link_reputation_blocked`, the blocked link as the step's copy writes it. Omitted otherwise.","nullable":true},"key":{"type":"string","description":"On `unfilled_template_key`, the template key the text still holds, such as `first_name` for\n`{first_name}`. Omitted otherwise.","nullable":true},"marker":{"type":"string","description":"On `unfilled_template_key`, that key as the text writes it, such as `{first_name}` or `[company]`.\nOmitted otherwise.","nullable":true},"retryAt":{"type":"string","description":"On a warm path Start's `guardrail_connector_monthly`, `guardrail_account_monthly`,\n`guardrail_connector_cooldown` and `guardrail_handoff_weekly`, when the limit frees up, in UTC. Omitted\notherwise.","format":"date-time","nullable":true},"workspaceId":{"type":"integer","description":"On `last_admin`, a workspace that needs a new admin before the account can be deleted. On\n`new_admin_not_found`, the workspace of the refused choice. Omitted otherwise.","format":"int64","nullable":true},"workspaceName":{"type":"string","description":"On `last_admin`, the name of that workspace. Omitted otherwise.","nullable":true},"class":{"type":"string","description":"On a `rate_limited` detail from your workspace's rate limits, the class of call that hit its limit:\n`read`, `write`, `bulk`, `heavy` or `sensitive`. Omitted otherwise.","nullable":true},"window":{"type":"string","description":"On that detail, the window whose limit was hit: `minute`, `day` or `bulkItemsDay`. Omitted\notherwise.","nullable":true}},"additionalProperties":false,"description":"One problem in an error: the field or limit it is about, a stable `code` and a `message`. The other fields\nappear only with the codes their descriptions name."},"Failure":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false on an error."},"error":{"allOf":[{"$ref":"#/components/schemas/ErrorBody"}],"description":"What went wrong."},"quotaResetAt":{"type":"string","description":"When the quota that refused the request frees up, in UTC. Set on some quota refusals. Omitted otherwise.","format":"date-time","nullable":true},"currentVersion":{"type":"integer","description":"The current revision of a workflow draft, on a draft save's `409 version_conflict`. Read the workflow\nagain, then send this value as `baseVersion`. Omitted otherwise.","format":"int32","nullable":true},"current":{"allOf":[{"$ref":"#/components/schemas/MeetingRepNotesCurrent"}],"description":"Your meeting notes and their version as stored now, on a meeting notes save's `409 version_conflict`.\nMerge your change, then save again with `baseVersion` set to `current.repNotesVersion`. Omitted\notherwise."},"refusal":{"allOf":[{"$ref":"#/components/schemas/Refusal"}],"description":"A copy of `error.refusal`, set on some billing refusals. Omitted otherwise."},"message":{"type":"string","description":"A copy of `error.message`, set together with `refusal`. Omitted otherwise.","nullable":true},"lookalikeSeeds":{"description":"How Kenso read each seed of a lookalike search, on its `422 no_usable_seeds`:\n`{resolved: [{input, companyId, personId, name, domain}], unresolved: [{input, reason}]}`. Use it to show\nwhy no seed was usable. Omitted otherwise."}},"additionalProperties":false,"description":"The body of every error, with a 4xx or 5xx status. Branch on `error.code`."},"InvalidationImpact":{"type":"object","properties":{"qualificationResponses":{"type":"integer","description":"Stored qualification answers the change would clear.","format":"int32"},"qualifiedFlags":{"type":"integer","description":"Contacts whose qualified result the change would clear.","format":"int32"},"segmentationReasoning":{"type":"integer","description":"Stored segmentation explanations the change would clear.","format":"int32"},"segmentationAssignmentsKept":{"type":"integer","description":"Contacts that keep their segment.","format":"int32"},"segmentationAssignmentsReset":{"type":"integer","description":"Contacts that go back to the default segment.","format":"int32"},"personalizationLines":{"type":"integer","description":"Personalized lines the change would clear.","format":"int32"},"personalizationLeads":{"type":"integer","description":"Contacts that would lose their personalized lines.","format":"int32"},"rewritingLines":{"type":"integer","description":"Rewritten lines the change would clear.","format":"int32"},"rewritingLeads":{"type":"integer","description":"Contacts that would lose their rewritten lines.","format":"int32"}},"additionalProperties":false,"description":"How much stored AI output a change would clear in each AI step of a campaign, and how many segment assignments it\nkeeps or resets."},"MeetingRepNotesCurrent":{"type":"object","properties":{"repNotes":{"type":"string","description":"Your notes as stored now. Empty before your first save."},"repNotesVersion":{"type":"integer","description":"The stored notes' version. Send it as `baseVersion` when you save again.","format":"int32"}},"additionalProperties":false,"description":"Your meeting notes as Kenso stores them now, sent with a `409 version_conflict` on a notes save."},"Pagination":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Send this value as `cursor` to get the next page. Omitted on the last page.","nullable":true},"hasMore":{"type":"boolean","description":"True when more items follow this page. Stop paging when it is false."},"total":{"type":"integer","description":"Deprecated: the same number as `totalCount`. Read `totalCount`.","format":"int32","nullable":true,"deprecated":true},"totalCount":{"type":"integer","description":"The number of items that match the list's filters, across all pages. Omitted when the list does not count them.","format":"int32","nullable":true},"isTotalCapped":{"type":"boolean","description":"True when `totalCount` stopped counting at its cap, so more items match than it says. Keep paging with\n`hasMore`. Omitted when `totalCount` is exact. Only `GET /v1/threads` with `q` caps its total.","nullable":true}},"additionalProperties":false,"description":"Where a list page ends and how to get the next page."},"RateLimitedText":{"type":"string","description":"The gateway's plain-text body of a `429` over the operation's own limit, until November 2026: `Number of requests exceeded. Please try again later.`","example":"Number of requests exceeded. Please try again later."},"Refusal":{"type":"object","properties":{"code":{"type":"string","description":"Stable refusal code in upper case, such as `CAMPAIGN_LIMIT_REACHED` or `INSUFFICIENT_CREDITS`."},"metric":{"type":"string","description":"What the limit counts: `Campaigns`, `Leads`, `Emails`, `LinkedInSeats` or `AiCredits`,\n`jobs_export_rows` or `funding_export_rows` for an export allowance, `credit_pack_credits`,\n`credit_spend_usd_7d`, `domains` or `mailboxes` for a limit on a new paying workspace, or for a\nKenso Lifetime cap its key: `workspaces`, `inboxes`, `contacts`, `email_verifications_day`,\n`email_verifications_month`, `people_results_day`, `company_results_day`,\n`funding_results_day`, `job_post_results_day`, `website_visits_month` or\n`visitor_lookups_day`. Omitted when a plan rule, not a count, refused the request.","nullable":true},"used":{"type":"integer","description":"How much of the limit is used, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"limit":{"type":"integer","description":"The limit, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"remaining":{"type":"integer","description":"How much of the limit is left, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"planType":{"type":"string","description":"The workspace's plan as its snake plan id, for example `free`, `legacy_core` or `growth`."},"remedy":{"type":"string","description":"What lifts the refusal: `Upgrade`, `BuyAddOn`, `UpdatePaymentMethod` or `ContactSupport`.\n`None` means no action of yours lifts it."},"unlocksAt":{"type":"string","description":"When the limit lifts by itself, in UTC: for a limit on a new paying workspace once it has paid an invoice, and for\na Kenso Lifetime daily or monthly cap its reset (00:00 UTC, or the 1st of the month). Omitted on every other\nrefusal.","format":"date-time","nullable":true},"requiredMillicredits":{"type":"integer","description":"On a credit refusal, the millicredits the action needed. 1,000 millicredits are one credit. Omitted on every\nother refusal.","format":"int64","nullable":true},"availableMillicredits":{"type":"integer","description":"On a credit refusal, the millicredits available. On `FREE_CREDITS_NOT_ELIGIBLE`, only the credits that may\npay for inboxes and domains. Omitted on every other refusal.","format":"int64","nullable":true},"restrictedMillicredits":{"type":"integer","description":"On `FREE_CREDITS_NOT_ELIGIBLE`, the free and bonus millicredits in the balance that cannot pay for inboxes\nand domains. Omitted on every other refusal.","format":"int64","nullable":true},"feature":{"type":"string","description":"On `PLAN_FEATURE_NOT_AVAILABLE`, the plan feature the plan does not include, in snake case (for example\n`website_visitor_id`). Omitted on every other refusal.","nullable":true},"requiredPlan":{"type":"string","description":"On `PLAN_FEATURE_NOT_AVAILABLE`, the cheapest plan that includes `feature`, in snake case (for example\n`growth`). For a feature the self-serve trial locks (`browser_runs`), the trial's own plan,\nwhich paying for unlocks it. Omitted on every other refusal.","nullable":true},"requiredTier":{"type":"integer","description":"On a Kenso Lifetime refusal, the lowest tier that lifts it: the next tier with a higher cap, or the lowest tier\nthat includes `feature`. Omitted at the top tier, when no tier includes the feature, and on every other\nrefusal.","format":"int32","nullable":true},"upgradeUrl":{"type":"string","description":"On a Kenso Lifetime refusal that a higher tier lifts, the AppSumo page where the buyer upgrades their license.\nOmitted until Kenso has read that page from AppSumo, when no tier lifts the refusal, and on every other refusal.","nullable":true}},"additionalProperties":false,"description":"Why a plan rule or usage limit refused the request, and how to lift it."},"ServiceUnavailableError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The body of a `503`: the error body (`Failure`). When Kenso cannot check the API key, its code is `auth_unavailable`, with `Retry-After: 5`. Until November 2026 the API key check in front of the operations answered `{ \"error\": \"Authentication is temporarily unavailable\" }` (`ApiKeyError`) there instead, so handle both shapes. Retry after the `Retry-After` seconds."},"TooManyRequestsError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The JSON body of a `429`: the error body (`Failure`), with code `rate_limited` or `quota_exceeded`, over your workspace's rate limits, your API key's own limit, the operation's own limit or a usage quota. Until November 2026, over your API key's own limit the API key check answered `{ \"error\": \"Rate limit exceeded\" }` (`ApiKeyError`), and over the operation's own limit the gateway answered plain text (`RateLimitedText`): `Number of requests exceeded. Please try again later.` A client built against those answers keeps working: handle each shape. Wait the `Retry-After` seconds."},"UnauthorizedError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The body of a `401`: the error body (`Failure`), whose `code` says what is wrong with the credential. Until November 2026, when the API key was not valid (unknown, expired or revoked, or its member no longer active), the API key check in front of the operations answered `{ \"error\": \"Invalid or revoked API key\" }` (`ApiKeyError`), and a request with no API key got a `401` that has no body. A client built against those answers keeps working: handle both shapes and a `401` with no body."}}}}