{"openapi":"3.0.4","info":{"title":"Kenso API: Placement tests","version":"1.1","description":"The Placement tests 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":"placement-tests","description":"Placement tests show where a campaign's email lands: the inbox, a promotions tab, spam, or nowhere. Kenso sends\nthe campaign's first email from your inboxes to seed mailboxes at Gmail, Google Workspace, Outlook and\nMicrosoft 365, then records where each copy arrived. Start a test, poll it until it completes, then read the\nresults by provider, sending inbox and seed. Kenso also tests your sending domains every week, and a campaign's\nlist includes those weekly tests for the domains it sends from. Where `GET /v1/placement-tests/availability`\nanswers `enabled: true`, the workspace's tests run on the Kenso seed network.","x-displayName":"Placement tests"}],"paths":{"/v1/placement-tests":{"get":{"tags":["placement-tests"],"summary":"List placement tests","description":"Lists the placement tests of one campaign, one inbox or one domain, newest first. A campaign's list holds the\ntests started for the campaign and Kenso's weekly tests of the domains the campaign sends from, even when a weekly\ntest belongs to another campaign. An inbox's list holds the tests of that inbox (its scope or one of its senders)\nand a domain's list the tests of that domain, from any campaign and either engine.\n            \nSend exactly one of the `campaignId`, `campaignIds`, `inboxId`, `domainId` and\n`domainIds` query parameters. Each item has the test's rates, each a fraction from 0 to 1 and omitted until\nthe test completes. For the results by provider, sending inbox and seed, get one test with\n`GET /v1/placement-tests/{placementTestId}`.\n            \n`domainIds` lists several domains in one call: 1 to 50 domain ids, comma-separated, such as\n`domainIds=4,9,12`. Each domain gets its newest `limit` tests, the ones the first page of its own\n`domainId` list holds; with `domainIds`, `limit` is from 1 to 20 and defaults to 20. The items come grouped by domain in the order of `domainIds`, each domain's tests\nnewest first. An id that is not a domain of this workspace has no items, where `domainId` answers\n`404`. This list takes no `cursor` and has no further pages (`pagination.hasMore` is false): to read\na domain's older tests, list it with `domainId`.\n            \n`campaignIds` lists several campaigns in one call: 1 to 100 campaign ids, comma-separated, such as\n`campaignIds=4,9,12`. Each campaign gets its newest `limit` tests, the ones the first page of its own\n`campaignId` list holds; with `campaignIds`, `limit` is from 1 to 20 and defaults to 20. The items\ncome grouped by campaign in the order of `campaignIds`, each campaign's tests newest first, and each item\nnames the campaign whose list it is in as `listedForCampaignId`. A weekly test of a domain several listed\ncampaigns send from is in each of their lists, so the same test `id` can come back more than once, and its own\n`campaignId` can be another campaign's. An id that is not a campaign of this workspace has no items, where\n`campaignId` answers `404`. This list takes no `cursor` and has no further pages\n(`pagination.hasMore` is false): to read a campaign's older tests, list it with `campaignId`.\n            \nErrors:\n            \n- `400 validation_failed`: not exactly one of `campaignId`, `campaignIds`, `inboxId`, `domainId` and `domainIds`, `domainIds` is not 1 to 50 positive ids, `campaignIds` is not 1 to 100 positive ids, `cursor` is sent with `domainIds` or `campaignIds`, `limit` is not from 1 to 200 (1 to 20 with `domainIds` or `campaignIds`), or `cursor` is not valid.\n- `404 not_found`: the campaign, inbox or domain is not in this workspace.\n            \nRequires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"placement-tests.list","parameters":[{"name":"campaignId","in":"query","description":"Campaign whose placement tests to list.","schema":{"type":"integer","format":"int64"}},{"name":"campaignIds","in":"query","description":"Campaigns whose placement tests to list: 1 to 100 campaign ids, comma-separated. Each campaign gets its newest\n`limit` tests, as `campaignId` gives its first page. Takes no `cursor`.","schema":{"type":"string"}},{"name":"inboxId","in":"query","description":"Inbox whose placement tests to list: tests it was the scope of or sent from, any campaign.","schema":{"type":"integer","format":"int64"}},{"name":"domainId","in":"query","description":"Domain whose placement tests to list, any campaign.","schema":{"type":"integer","format":"int64"}},{"name":"domainIds","in":"query","description":"Domains whose placement tests to list: 1 to 50 domain ids, comma-separated. Each domain gets its newest\n`limit` tests, as `domainId` gives its first page. Takes no `cursor`.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size: defaults to 50, maximum 200. With `domainIds`, the tests per domain, and with\n`campaignIds`, the tests per campaign: defaults to 20, maximum 20.","schema":{"maximum":200,"minimum":1,"type":"integer","format":"int32"}},{"name":"cursor","in":"query","description":"Opaque cursor from a previous page.","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/PlacementTestListResponse"}}}},"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"}},"post":{"tags":["placement-tests"],"summary":"Start a placement test","description":"Sends an email to seed mailboxes and records where each copy lands. The call returns the test at once. Poll\n`GET /v1/placement-tests/{placementTestId}` until `status` is `completed` or `failed`;\nresults arrive in about an hour. A workspace runs its tests on one of two engines: the Kenso seed network where\n`GET /v1/placement-tests/availability` answers `enabled: true`, the mailbox provider's engine\neverywhere else.\n            \nKenso seed network (paid plans only): the seed network covers Google Workspace at launch; Microsoft 365 joins\nwhen it has enough seeds, and `providers[].tested` says which ran. Scope: `inboxId` tests one inbox,\n`domainId` the domain's inboxes, neither the campaign's senders (needs `campaignId`). Copy: the\ncampaign's (`campaignId`), or custom `subject` and `body` together. `control: true` also sends\na plain message from the same senders to tell a copy problem from a domain problem. `openPixel: true` is\nrefused: open tracking is unavailable, Kenso adds no open-tracking pixel. `trackLinks: false` sends the body's links as written instead of as tracked links (default\ntrue); the test's `trackLinks` says which it used. A `200` keeps the running test's settings, so run a\ntracked and an untracked test one after the other or from different scopes. `followUp` also sends each seed a second email from the\nsame inbox in the first email's thread (`body`, `format`, `delayMinutes` 5 to 4320, optional\n`subject`), only once the first email was sent. The test, its verdict and its scope stay busy until the\nfollow-up is read, up to the delay plus about an hour: a create for the same scope meanwhile answers `200` with\nthis test, so compare two follow-ups from different inboxes. `followUp` and `seeds[].followUp` hold its results. Example: `{ \"domainId\": 1369, \"campaignId\": 8865, \"control\": true }`. Answers `201`\nwith the new test, or `200` with the test already running for that scope; the body is the detail model, or\nonly the test's own fields when the read replica has not caught up yet (poll the detail). An id of 0 counts as\nabsent. Budget: `placementTestCreatesNative` (10 a day, 60 in 30 days), `placementTestCreatesNativeTrial`\nwhile trialing (2 a day, 8 in 30 days); over it `429 quota_exceeded` naming the limit, with\n`Retry-After`. Kenso staff have a daily cap instead.\n            \nErrors on the Kenso seed network:\n            \n- `400 validation_failed`: both `inboxId` and `domainId`, `randomScope`, only one of `subject` and `body`, or no `campaignId` where the copy or the scope needs one; a `followUp` with no `body`, a `format` other than `plain` or `html` or one the body does not match, or a `delayMinutes` outside 5 to 4320; a `followUp` while follow-ups are off (detail code `follow_up_unavailable`). Detail code `open_tracking_unavailable` on `openPixel` for `openPixel: true`.\n- `402 plan_limit_reached` with `error.refusal`: the plan has no placement tests.\n- `404 not_found`: the campaign, inbox or domain is not in this workspace.\n- `409 demo_workspace`; `409 control_unavailable`: not enough seeds for the control arm; `409 invalid_state`: no inbox can send (`details[].code` `sender_unavailable`), or a test for this scope is still starting (`placement_test_starting`, try again in a minute).\n- `422` with the reason as the code: `copy_unresolved`, `copy_not_neutral`, `copy_link_listed`, `copy_too_large`, `copy_brand_domain`, `copy_has_attachments`, `sender_blocked`. `details` name the field or the inbox.\n- `429 rate_limited`: an inbox's or the staff daily test cap (`details[].code` `sender_daily_cap` or `staff_daily_cap`).\n- `503` `seed_network_busy`, `link_check_unavailable` or `placement_native_paused`: try again later.\n            \nThe mailbox provider's engine: send `campaignId` and exactly one of `domainId` or `inboxId`; `control`,\n`subject`, `body`, `trackLinks` and `followUp` are ignored. With `domainId`, Kenso sends from the domain's inboxes. With\n`inboxId`, it sends from that inbox only. With `randomScope` set to true, Kenso picks a random eligible\ndomain in the workspace and ignores both. The test can only send from active inboxes that Kenso manages. Example:\n`{ \"campaignId\": 812, \"inboxId\": 44 }`.\n            \nKenso tests the first active step of the campaign's sequence and fills its variables from a sample contact. The\nother body fields choose which copy and which contact. With `openPixel` set to true, the copy carries the\ncampaign open pixel, so you can compare placement with the pixel on and off. The answer's `openPixelHost`\nnames the host the pixel loads from.\n            \nIf a test of the same campaign on the same inbox, or for a domain test the same domain, is still pending or\nrunning, Kenso returns that test instead of starting a second one.\n            \nTests cost the workspace no credits, so Kenso limits how many tests a workspace can start per day and per 30\ndays. A call that fails before the test starts does not count against the limit.\n            \nErrors on the mailbox provider's engine:\n            \n- `400 validation_failed`: `campaignId` is missing, or the body has both or neither of `domainId` and `inboxId` while `randomScope` is false.\n- `404 not_found`: the campaign, contact, domain or inbox is not in this workspace.\n- `409 invalid_state`: Kenso cannot build or send the test, and the message says why. The campaign has no email copy, no contact has its personalization filled yet, the copy has a broken `{spin:...}` block, the domain or inbox has no active inbox that Kenso manages, the workspace has no eligible domain for `randomScope`, the provider refused the sending inboxes, or the workspace is a demo workspace.\n- `409 invalid_state` with `openPixel`: the copy is plain text, neither `link.` nor `unsub.` on the sending domain serves the pixel, or a test with the other pixel setting is already running for the campaign and domain.\n- `429 rate_limited` or `429 quota_exceeded`: the workspace reached its placement test limit. Try again after the `Retry-After` seconds.\n- `503 service_unavailable`: Kenso can't start placement tests right now. Try again later.\n            \nRequires Delivery edit.\n\nRate limit: 10 calls a minute per API key, on top of the workspace limits.","operationId":"placement-tests.create","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":{"$ref":"#/components/schemas/CreatePlacementTestRequest"}}}},"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/PlacementTestResponse"}}}},"201":{"description":"Created","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/PlacementTestResponse"}}}},"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"]},"402":{"description":"Payment Required","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":["plan_limit_reached"]},"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"]},"409":{"description":"Conflict","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":["control_unavailable","demo_workspace","invalid_state"]},"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":["quota_exceeded","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"}}},"/v1/placement-tests/{placementTestId}":{"get":{"tags":["placement-tests"],"summary":"Get a placement test","description":"Returns one placement test with its full results. Poll it after you start a test, until `status` is\n`completed` or `failed`.\n            \nBesides the fields in the list, the test has `type`, `senderInboxIds`, the `subject` and\n`body` it sent, and `openPixelHost` when it carried the open pixel. Once the test completes, it also\nhas `startedAt`, `sentCount`, `counts`, and the results per seed provider (`providers`),\nper sending inbox (`senders`) and per seed mailbox (`seeds`), plus any `errors` the provider\nreported. Seed addresses are masked. Rates are fractions from 0 to 1.\n            \nThe `earlierTests` list holds up to 10 earlier tests of the same `campaignId` and `domainId`,\nwhichever are set, newest first, so you can show a trend. A test of one inbox that has no domain has no earlier tests.\n            \nErrors:\n            \n- `404 not_found`: the placement test is not in this workspace.\n            \nRequires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"placement-tests.get","parameters":[{"name":"placementTestId","in":"path","description":"The placement test'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/PlacementTestResponse"}}}},"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/placement-tests/availability":{"get":{"tags":["placement-tests"],"summary":"Return what the start dialog needs to offer a Kenso placement test.","description":"Always `200`. `enabled: false` means this workspace keeps the mailbox provider's engine.\n`planAllowed`: the plan can start Kenso tests. `providers`: each seed provider and whether it runs\ntests now. `control`: whether a test can add the control arm, and why not. The test counters are what the\nworkspace's budget leaves today and this month (omitted when unknown); `senderTestsPerDay` is the cap per\nsending inbox. Requires Delivery view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"placement-tests.availability","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"}}],"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/PlacementAvailabilityResponse"}}}},"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"}}}},"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."},"CreatePlacementTestRequest":{"type":"object","properties":{"campaignId":{"type":"integer","description":"Campaign whose email Kenso tests. Required, except on the Kenso engine for a test of custom `subject` and\n`body` sent from an `inboxId` or `domainId`.","format":"int64","nullable":true},"inboxId":{"type":"integer","description":"Inbox the test sends from. Send it or `domainId`, not both. Ignored when `randomScope` is true.","format":"int64","nullable":true},"domainId":{"type":"integer","description":"Domain whose inboxes send the test. Send it or `inboxId`, not both. Ignored when `randomScope` is\ntrue.","format":"int64","nullable":true},"sequenceVersionId":{"type":"integer","description":"Saved version of the campaign's sequence to test. When set, Kenso ignores `campaignSegmentId`,\n`randomSegment` and `randomCopyVersion` to choose the copy. Omitted tests the sequence as it is saved now.","format":"int64","nullable":true},"sampleVariables":{"type":"object","additionalProperties":{"type":"string"},"description":"Values for the copy's variables, keyed by variable name, such as `{\"firstName\": \"Dana\"}`. They win over the\nsample contact's values. Kenso ignores blank keys and values.","nullable":true},"campaignSegmentId":{"type":"integer","description":"Campaign segment whose copy to test. A segment without its own copy uses the campaign's default copy. Omitted\nuses the sample contact's segment, or the default copy when there is no sample contact.","format":"int64","nullable":true},"contactId":{"type":"integer","description":"Contact in the campaign whose data fills the copy's variables. If the copy uses a variable this contact has no\nvalue for yet, the call answers `409 invalid_state`.","format":"int64","nullable":true},"randomSegment":{"type":"boolean","description":"When true and `campaignSegmentId` is omitted, Kenso tests the copy of a random segment of the campaign.\nDefault false."},"randomLead":{"type":"boolean","description":"When true and `contactId` is omitted, Kenso fills the copy from a sample contact of the campaign, and\nprefers contacts whose AI personalization is filled. Default false. Without it, Kenso uses a sample contact only\nwhen the copy has variables that need one."},"randomScope":{"type":"boolean","description":"When true, Kenso sends from a random eligible domain in the workspace and ignores `domainId` and\n`inboxId`. Default false."},"randomCopyVersion":{"type":"boolean","description":"When true and `sequenceVersionId` is omitted, Kenso tests a random saved version of the sequence. Default\nfalse."},"openPixel":{"type":"boolean","description":"The mailbox provider's engine only: when true, the copy carries the campaign open pixel, loaded from\n`link.` or `unsub.` on the sending domain, whichever serves it first. On the Kenso seed network open\ntracking is unavailable: Kenso adds no open-tracking pixel, so `true` is 400 `validation_failed` with\ndetail code `open_tracking_unavailable` and no test starts. Default false."},"trackLinks":{"type":"boolean","description":"Kenso engine only: when false, every send of the test carries the body's links as written, with no click\ntracking. Default true: links go through tracked links on the sending domain."},"control":{"type":"boolean","description":"Kenso engine only: also send a plain control message from the same senders to a second set of seeds, to tell a\ncopy problem from a domain problem. Default false."},"subject":{"type":"string","description":"Kenso engine only: custom copy to test instead of the campaign's. Give it with `body`.","nullable":true},"body":{"type":"string","description":"Kenso engine only: custom copy, HTML or plain text. Give it with `subject`.","nullable":true},"followUp":{"allOf":[{"$ref":"#/components/schemas/PlacementTestFollowUpRequest"}],"description":"Kenso engine only: a second email each seed gets from the same inbox, in the first email's thread, once the first\nemail was sent and `delayMinutes` passed. Omitted sends only the first email. The test, its verdict and its\nscope stay busy until the follow-up is read, so compare two follow-ups from different inboxes."}},"additionalProperties":false,"description":"What a placement test sends and where from. On the mailbox provider's engine, send `campaignId` and exactly one\nof `domainId` or `inboxId`, unless `randomScope` is true. On the Kenso engine, send `inboxId`,\n`domainId` or neither (the campaign's senders), with the campaign's copy or `subject` and `body`."},"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."},"PlacementAuthSummary":{"type":"object","properties":{"checked":{"type":"integer","format":"int32"},"spfPass":{"type":"integer","format":"int32"},"dkimPass":{"type":"integer","format":"int32"},"dmarcPass":{"type":"integer","format":"int32"},"compauthPass":{"type":"integer","format":"int32"},"allPass":{"type":"integer","description":"Messages where SPF, DKIM and DMARC all passed.","format":"int32"}},"additionalProperties":false,"description":"Found messages that carry authentication results, and how many passed each check."},"PlacementAvailability":{"type":"object","properties":{"enabled":{"type":"boolean","description":"The Kenso engine runs for this workspace (flag on, not paused)."},"planAllowed":{"type":"boolean","description":"The workspace's plan can start Kenso tests (paid plans; staff and Kenso workspaces always)."},"providers":{"type":"array","items":{"$ref":"#/components/schemas/PlacementProviderAvailability"},"description":"Every seed provider, `google_workspace` then `microsoft_365`, and whether it runs tests now."},"seedsPerArm":{"type":"integer","description":"Seed inboxes each arm sends to across the active providers.","format":"int32"},"control":{"allOf":[{"$ref":"#/components/schemas/PlacementControlAvailability"}],"description":"Whether a test can add the control arm; `reason` says why not."},"testsLeftToday":{"type":"integer","format":"int32","nullable":true},"testsLeftThisMonth":{"type":"integer","format":"int32","nullable":true},"testsPerDay":{"type":"integer","format":"int32","nullable":true},"testsPerMonth":{"type":"integer","format":"int32","nullable":true},"senderTestsPerDay":{"type":"integer","description":"Tests one sending inbox can be part of in 24 hours.","format":"int32"}},"additionalProperties":false,"description":"What the start dialog needs. `enabled: false` means the workspace keeps the mailbox provider's\nengine. Test counters are omitted when unknown; staff and Kenso workspaces have no month counter."},"PlacementAvailabilityResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/PlacementAvailability"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"PlacementControl":{"type":"object","properties":{"inboxRate":{"type":"number","format":"double","nullable":true},"spamRate":{"type":"number","format":"double","nullable":true},"categoryRate":{"type":"number","format":"double","nullable":true},"missingRate":{"type":"number","format":"double","nullable":true},"counts":{"allOf":[{"$ref":"#/components/schemas/PlacementCounts"}],"description":"Seed copies per placement. `total` is the sum of the other five counts."},"providers":{"type":"array","items":{"$ref":"#/components/schemas/PlacementProviderResult"}}},"additionalProperties":false,"description":"The control arm: the same senders sent a plain message. Rates are fractions from 0 to 1."},"PlacementControlAvailability":{"type":"object","properties":{"available":{"type":"boolean"},"reason":{"type":"string","nullable":true}},"additionalProperties":false,"description":"Whether a test can add the control arm; `reason` says why not."},"PlacementCounts":{"type":"object","properties":{"inbox":{"type":"integer","description":"Copies that landed in the inbox (the primary tab in Gmail).","format":"int32"},"promotions":{"type":"integer","description":"Copies that landed in the promotions tab or another category tab.","format":"int32"},"other":{"type":"integer","description":"Copies that landed in any other folder.","format":"int32"},"spam":{"type":"integer","description":"Copies that landed in spam or junk.","format":"int32"},"missing":{"type":"integer","description":"Copies that never arrived.","format":"int32"},"total":{"type":"integer","description":"All copies, the sum of the five counts.","format":"int32"}},"additionalProperties":false,"description":"Seed copies per placement. `total` is the sum of the other five counts."},"PlacementFollowUp":{"type":"object","properties":{"format":{"type":"string","description":"`plain` or `html`."},"delayMinutes":{"type":"integer","description":"Minutes after the first email was sent that the follow-up went out.","format":"int32"},"subject":{"type":"string","description":"Subject the follow-up sent, before its variables were filled.","nullable":true},"body":{"type":"string","description":"Body the follow-up sent, before its variables were filled. Only when you get one test.","nullable":true},"counts":{"allOf":[{"$ref":"#/components/schemas/PlacementCounts"}],"description":"Follow-ups per placement. Only when you get one test."},"providers":{"type":"array","items":{"$ref":"#/components/schemas/PlacementProviderResult"},"description":"The follow-up's results by seed provider. Only when you get one test.","nullable":true}},"additionalProperties":false,"description":"A Kenso test's follow-up, sent from the same inbox to the same seed in the first email's thread."},"PlacementMicrosoftSummary":{"type":"object","properties":{"scored":{"type":"integer","format":"int32"},"bulkHigh":{"type":"integer","format":"int32"},"medianBcl":{"type":"number","format":"double","nullable":true},"medianScl":{"type":"number","format":"double","nullable":true}},"additionalProperties":false,"description":"Microsoft's scores over found Microsoft 365 messages. `bulkHigh`: messages with a high bulk score."},"PlacementProgress":{"type":"object","properties":{"planned":{"type":"integer","format":"int32"},"sent":{"type":"integer","format":"int32"},"read":{"type":"integer","format":"int32"},"waiting":{"type":"integer","format":"int32"},"failed":{"type":"integer","format":"int32"},"finalBy":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":false,"description":"A Kenso test's sends by state: `read` found or missing, `waiting` not read yet, `failed` not sent or\nnot readable. `finalBy` is when the last read is due while anything waits."},"PlacementProviderAvailability":{"type":"object","properties":{"provider":{"type":"string"},"active":{"type":"boolean"}},"additionalProperties":false},"PlacementProviderBreakdown":{"type":"object","properties":{"googleWorkspace":{"type":"number","description":"Inbox rate at Google Workspace seed mailboxes.","format":"double","nullable":true},"googlePersonal":{"type":"number","description":"Inbox rate at personal Gmail seed mailboxes.","format":"double","nullable":true},"outlookWorkspace":{"type":"number","description":"Inbox rate at Microsoft 365 seed mailboxes.","format":"double","nullable":true},"outlookPersonal":{"type":"number","description":"Inbox rate at personal Outlook seed mailboxes.","format":"double","nullable":true}},"additionalProperties":false,"description":"Inbox rate by type of seed mailbox, each a fraction from 0 to 1. A field is omitted when the test had no seed\nmailboxes of that type."},"PlacementProviderResult":{"type":"object","properties":{"provider":{"type":"string","description":"Seed mailbox provider, such as `gmail`, `google_workspace`, `outlook` or `microsoft_365`.\n`unknown` when the testing provider did not say."},"inbox":{"type":"integer","description":"Copies that landed in the inbox (the primary tab in Gmail).","format":"int32"},"promotions":{"type":"integer","description":"Copies that landed in the promotions tab or another category tab.","format":"int32"},"other":{"type":"integer","description":"Copies that landed in any other folder.","format":"int32"},"spam":{"type":"integer","description":"Copies that landed in spam or junk.","format":"int32"},"missing":{"type":"integer","description":"Copies that never arrived.","format":"int32"},"total":{"type":"integer","description":"All copies to this provider, the sum of the five counts.","format":"int32"},"tested":{"type":"boolean","description":"Kenso: false when the test sent nothing to this provider (not in the seed network yet), with zero counts.","nullable":true},"folders":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Kenso: found messages per folder or tab, such as `primary` or `junk`, plus `missing`.","nullable":true},"authentication":{"allOf":[{"$ref":"#/components/schemas/PlacementAuthSummary"}],"description":"Kenso: SPF, DKIM, DMARC and compauth over the found messages that carry them."},"microsoft":{"allOf":[{"$ref":"#/components/schemas/PlacementMicrosoftSummary"}],"description":"Kenso, `microsoft_365` only: Microsoft's spam (SCL) and bulk (BCL) scores."},"medianArrivalSeconds":{"type":"integer","description":"Kenso: median seconds from send to arrival over found messages.","format":"int32","nullable":true}},"additionalProperties":false,"description":"Seed copies per placement at one seed mailbox provider."},"PlacementSeedAuth":{"type":"object","properties":{"spf":{"type":"string","nullable":true},"dkim":{"type":"string","nullable":true},"dmarc":{"type":"string","nullable":true},"compauth":{"type":"string","nullable":true}},"additionalProperties":false,"description":"One message's authentication results: `pass`, `fail`, `softfail`, `none` and the like."},"PlacementSeedMicrosoft":{"type":"object","properties":{"scl":{"type":"integer","format":"int32","nullable":true},"bcl":{"type":"integer","format":"int32","nullable":true},"cat":{"type":"string","nullable":true},"sfv":{"type":"string","nullable":true}},"additionalProperties":false},"PlacementSeedResult":{"type":"object","properties":{"seed":{"type":"string","description":"Seed address, masked to its first letter and its domain, such as `d***@gmail.com`. Kenso staff see it in\nfull."},"provider":{"type":"string","description":"Seed mailbox provider, such as `gmail`, `google_workspace`, `outlook` or `microsoft_365`."},"senderEmail":{"type":"string","description":"Address of the sending inbox, in lowercase."},"placement":{"type":"string","description":"Where the copy landed: `inbox`, `promotions`, `other`, `spam` or `missing`, or\n`pending` on a Kenso seed not read yet."},"folder":{"type":"string","description":"Gmail label or Outlook folder the copy landed in, such as `SPAM` or `Junk Email`. Omitted when not\nreported.","nullable":true},"detectedAt":{"type":"string","description":"When the copy was found in the seed mailbox, in UTC. Omitted when not reported.","format":"date-time","nullable":true},"arm":{"type":"string","description":"Kenso: `main` or `control`.","nullable":true},"status":{"type":"string","description":"Kenso: `waiting`, `found`, `missing`, `send_failed` or `read_failed`.","nullable":true},"tab":{"type":"string","description":"Kenso: the folder or tab the message was in, such as `primary`, `promotions` or `junk`.","nullable":true},"authentication":{"allOf":[{"$ref":"#/components/schemas/PlacementSeedAuth"}],"description":"One message's authentication results: `pass`, `fail`, `softfail`, `none` and the like."},"microsoft":{"allOf":[{"$ref":"#/components/schemas/PlacementSeedMicrosoft"}],"description":"Kenso, Microsoft 365 seeds: the message's SCL, BCL, CAT and SFV."},"arrivalSeconds":{"type":"integer","format":"int32","nullable":true},"followUp":{"allOf":[{"$ref":"#/components/schemas/PlacementSeedResult"}],"description":"Kenso, a test with a follow-up: where the follow-up to this seed landed, in this same shape. Omitted otherwise."}},"additionalProperties":false,"description":"Where one seed mailbox received the copy from one sending inbox."},"PlacementSenderResult":{"type":"object","properties":{"email":{"type":"string","description":"Address of the sending inbox, in lowercase."},"inbox":{"type":"integer","description":"Copies that landed in the inbox (the primary tab in Gmail).","format":"int32"},"promotions":{"type":"integer","description":"Copies that landed in the promotions tab or another category tab.","format":"int32"},"other":{"type":"integer","description":"Copies that landed in any other folder.","format":"int32"},"spam":{"type":"integer","description":"Copies that landed in spam or junk.","format":"int32"},"missing":{"type":"integer","description":"Copies that never arrived.","format":"int32"},"total":{"type":"integer","description":"All copies from this inbox, the sum of the five counts. 0 when its mail reached no seed.","format":"int32"}},"additionalProperties":false,"description":"Seed copies per placement for one sending inbox."},"PlacementTest":{"type":"object","properties":{"id":{"type":"integer","description":"Placement test id.","format":"int64"},"campaignId":{"type":"integer","description":"Campaign the test belongs to. In a campaign's list, a weekly domain test can belong to another campaign that\nsends from the same domain.","format":"int64","nullable":true},"listedForCampaignId":{"type":"integer","description":"The campaign whose list this item is in, when you list several campaigns with `campaignIds`. Omitted\neverywhere else.","format":"int64","nullable":true},"inboxId":{"type":"integer","description":"Inbox the test was limited to. Omitted for a test of a whole domain.","format":"int64","nullable":true},"domainId":{"type":"integer","description":"Domain the test sent from. Omitted when the test has no domain.","format":"int64","nullable":true},"sequenceId":{"type":"integer","description":"Sequence whose copy the test sent. Omitted in the answer to a start and when not recorded.","format":"int64","nullable":true},"sequenceVersionId":{"type":"integer","description":"Saved sequence version the test sent. Omitted when the test sent the sequence as it was saved at the time.","format":"int64","nullable":true},"status":{"type":"string","description":"Test status: `pending` (waiting to send), `running` (sent, and Kenso is checking the seed\nmailboxes), `completed` or `failed`."},"inboxRate":{"type":"number","description":"Share of the seed copies that landed in the inbox, a fraction from 0 to 1. Omitted until the test completes.","format":"double","nullable":true},"spamRate":{"type":"number","description":"Share of the seed copies that landed in spam, a fraction from 0 to 1. Omitted until the test completes.","format":"double","nullable":true},"categoryRate":{"type":"number","description":"Share of the seed copies that landed in a promotions or other category tab, a fraction from 0 to 1. Omitted\nuntil the test completes.","format":"double","nullable":true},"missingRate":{"type":"number","description":"Share of the seed copies that never arrived, a fraction from 0 to 1. Omitted until the test completes.","format":"double","nullable":true},"code":{"type":"string","description":"The testing provider's reference for this test. Omitted when there is none.","nullable":true},"openPixelHost":{"type":"string","description":"Host the campaign open pixel loaded from, for a test started with `openPixel` set to true. Returned when\nyou start a test and when you get one, not in the list. Omitted when the test carried no pixel.","nullable":true},"provider":{"type":"string","description":"Name of the testing provider that ran the test, in lowercase, such as `kenso` for a test on the Kenso seed\nnetwork. Omitted when not recorded. Prefer providerKind.","nullable":true},"providerKind":{"type":"string","description":"The testing provider in neutral words: `kenso` for the Kenso seed network, `mailbox_provider` for the\nmailbox provider's engine, or `other` (older tests). Omitted when not recorded.","nullable":true},"scope":{"type":"string","description":"Kenso tests: `inbox`, `domain` or `campaign` (the campaign's senders). Omitted otherwise.","nullable":true},"verdict":{"allOf":[{"$ref":"#/components/schemas/PlacementVerdict"}],"description":"Kenso tests: the scored cause and its one-line summary. Omitted until the test completes."},"hasControl":{"type":"boolean","description":"Kenso tests: true when the test also sent the plain control message. Omitted on other tests.","nullable":true},"trackLinks":{"type":"boolean","description":"Kenso tests: false when the test sent the body's links as written, true when it sent them as tracked links.\nOmitted on other tests.","nullable":true},"providersTested":{"type":"array","items":{"type":"string"},"description":"Kenso tests: the seed providers it sent to, `google_workspace` and `microsoft_365`.","nullable":true},"dataPoints":{"type":"array","items":{"$ref":"#/components/schemas/PlacementProviderBreakdown"},"description":"Inbox rate by type of seed mailbox, as a list with one entry. Omitted when the test has no results by provider.","nullable":true},"createdAt":{"type":"string","description":"When the test was created, in UTC.","format":"date-time"},"completedAt":{"type":"string","description":"When the test completed, in UTC. Omitted until then.","format":"date-time","nullable":true},"type":{"type":"string","description":"Kind of test: `weekly` (Kenso's weekly test of a sending domain), `on_demand` (a test someone\nstarted) or `pre_launch` (a test run before a campaign launched). Only when you get one test.","nullable":true},"startedAt":{"type":"string","description":"When the provider started sending the test, in UTC. Omitted until the test completes.","format":"date-time","nullable":true},"sentCount":{"type":"integer","description":"Test emails the provider sent. 0 when it sent none, for example because it refused every sending inbox (see\n`errors`). Omitted until the test completes.","format":"int32","nullable":true},"failureReason":{"type":"string","description":"Why the test failed, when `status` is `failed`. Omitted otherwise.","nullable":true},"senderInboxIds":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Ids of the inboxes the test sent from. Omitted when not recorded.","nullable":true},"subject":{"type":"string","description":"Subject line the test sent, with its variables filled. Omitted for older tests that did not store it.","nullable":true},"body":{"type":"string","description":"Body the test sent, with its variables filled. Omitted for older tests that did not store it.","nullable":true},"counts":{"allOf":[{"$ref":"#/components/schemas/PlacementCounts"}],"description":"Seed copies per placement across the whole test. Omitted until the test completes."},"providers":{"type":"array","items":{"$ref":"#/components/schemas/PlacementProviderResult"},"description":"Seed copies per placement for each seed mailbox provider, in the order `gmail`, `google_workspace`,\n`outlook`, `microsoft_365`, then any other. Omitted until the test completes.","nullable":true},"senders":{"type":"array","items":{"$ref":"#/components/schemas/PlacementSenderResult"},"description":"Seed copies per placement for each sending inbox, including an inbox whose mail reached no seed. Omitted until\nthe test completes.","nullable":true},"seeds":{"type":"array","items":{"$ref":"#/components/schemas/PlacementSeedResult"},"description":"One row per seed mailbox and sending inbox. Omitted until the test completes.","nullable":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/PlacementTestError"},"description":"Errors the provider reported, such as a sending inbox it could not use, oldest first and at most 50. On a Kenso\ntest, the seed providers it skipped and the sends and reads that failed. Omitted when there are none.","nullable":true},"control":{"allOf":[{"$ref":"#/components/schemas/PlacementControl"}],"description":"Kenso detail with `hasControl`: the control arm's rates, counts and providers."},"progress":{"allOf":[{"$ref":"#/components/schemas/PlacementProgress"}],"description":"Kenso detail: sends by state and when the final read is due."},"followUp":{"allOf":[{"$ref":"#/components/schemas/PlacementFollowUp"}],"description":"Kenso tests started with `followUp`: its settings, and on one test its body and results. The other result\nfields describe the first email. Omitted on other tests."},"earlierTests":{"type":"array","items":{"$ref":"#/components/schemas/PlacementTestTrend"},"description":"Up to 10 earlier tests of the same `campaignId` and `domainId`, whichever are set, newest first.\nEmpty for a test of one inbox that has no domain. Only when you get one test.","nullable":true}},"additionalProperties":false,"description":"One placement test, with where the copies of a campaign email landed in the seed mailboxes. Rates are fractions\nfrom 0 to 1."},"PlacementTestError":{"type":"object","properties":{"message":{"type":"string","description":"The provider's error text, at most 500 characters."},"at":{"type":"string","description":"When the error happened, in UTC. Omitted when not reported.","format":"date-time","nullable":true}},"additionalProperties":false,"description":"An error the testing provider reported for a placement test."},"PlacementTestFollowUpRequest":{"required":["body"],"type":"object","properties":{"body":{"type":"string","description":"The follow-up's body, HTML or plain text. Required."},"format":{"type":"string","description":"`plain` or `html`, and it must match the body. Omitted reads it from the body.","nullable":true},"delayMinutes":{"type":"integer","description":"Minutes after the first email was sent, 5 to 4320 (3 days).","format":"int32"},"subject":{"type":"string","description":"The follow-up's subject. Omitted sends \"Re: \" and the first email's subject.","nullable":true}},"additionalProperties":false,"description":"The follow-up of a Kenso placement test. The test's `openPixel` and `trackLinks` apply to it too."},"PlacementTestListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PlacementTest"},"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."},"PlacementTestResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/PlacementTest"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"PlacementTestTrend":{"type":"object","properties":{"id":{"type":"integer","description":"Placement test id.","format":"int64"},"campaignId":{"type":"integer","description":"Campaign the earlier test belongs to.","format":"int64","nullable":true},"inboxId":{"type":"integer","description":"Inbox the earlier test was limited to. Omitted for a test of a whole domain.","format":"int64","nullable":true},"domainId":{"type":"integer","description":"Domain the earlier test sent from. Omitted when it has no domain.","format":"int64","nullable":true},"status":{"type":"string","description":"Test status: `pending`, `running`, `completed` or `failed`."},"inboxRate":{"type":"number","description":"Share of the seed copies that landed in the inbox, a fraction from 0 to 1. Omitted until the test completes.","format":"double","nullable":true},"spamRate":{"type":"number","description":"Share of the seed copies that landed in spam, a fraction from 0 to 1. Omitted until the test completes.","format":"double","nullable":true},"categoryRate":{"type":"number","description":"Share of the seed copies that landed in a promotions or other category tab, a fraction from 0 to 1. Omitted\nuntil the test completes.","format":"double","nullable":true},"missingRate":{"type":"number","description":"Share of the seed copies that never arrived, a fraction from 0 to 1. Omitted until the test completes.","format":"double","nullable":true},"createdAt":{"type":"string","description":"When the earlier test was created, in UTC.","format":"date-time"},"completedAt":{"type":"string","description":"When the earlier test completed, in UTC. Omitted until then.","format":"date-time","nullable":true}},"additionalProperties":false,"description":"An earlier placement test, for a trend. Rates are fractions from 0 to 1."},"PlacementVerdict":{"type":"object","properties":{"cause":{"type":"string"},"summary":{"type":"string","nullable":true}},"additionalProperties":false,"description":"A Kenso test's verdict. `cause`: `auth_failing`, `copy`, `reputation`, `microsoft_bulk`,\n`one_provider`, `healthy` or `mixed`."},"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."}}}}