{"openapi":"3.0.4","info":{"title":"Kenso API: Image variables","version":"1.1","description":"The Image variables 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":"image-variables","description":"Image variables put an image into a campaign's emails through a `{{key}}` token. A `shared` variable has\none image that every contact gets. A `per_prospect` variable has one image per contact, which Kenso generates\nfrom a prompt and charges in credits for each ready image. A campaign has at most 5 image variables, and Kenso sends\nimages only when the workspace has a tracking link host. All prices are in credits. Read the contacts' images with\n`GET /v1/campaigns/{campaignId}/images`.","x-displayName":"Image variables"}],"paths":{"/v1/campaigns/{campaignId}/image-variables":{"get":{"tags":["image-variables"],"summary":"List a campaign's image variables","description":"Returns the campaign's image variables, ordered by key, in one page: `hasMore` is always false. Next to\n`data`, the response has what you need to set up a variable:\n            \n- `linkHostReady`: whether the workspace has a tracking link host. Without one, you cannot create or send an\n  image variable.\n- `coverage`: how many contacts Kenso counted (`leads`), and how many of them have each reference picture.\n- `models`: the image models you can pick, each with its estimated credits per still image and\n  `supportsGif`, whether a variable on it can be an animated GIF.\n            \nErrors:\n            \n- `404 not_found`: the campaign does not exist in this workspace.\n            \nRequires Campaigns view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `campaign_images` feature on your workspace. Until it is on, calls answer 404.","operationId":"image-variables.list","parameters":[{"name":"campaignId","in":"path","description":"Id of the campaign.","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/ImageVariableListResponse"}}}},"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-features":["campaign_images"],"x-ken-permission":{"kind":"page","page":"campaigns","access":"view","summary":"Campaigns view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"post":{"tags":["image-variables"],"summary":"Create an image variable","description":"Adds an image variable to the campaign. Returns `201` with the variable and its `Location`. A new\nvariable is off and generates nothing: read its cost with the estimate call, then turn it on with `PATCH`\nand `enabled: true`. Sending `enabled: true` here is a `400`.\n            \n`key` and `kind` are required and never change later. Kenso normalizes `key` to lowercase snake_case,\nso `Hero Image` becomes `hero_image` and steps use it as `{{hero_image}}`. The key shares one set of\nnames with the campaign's custom variables and AI variables. A `per_prospect` variable needs a `prompt`.\nA `shared` variable can use only the `sender_logo` reference, because it has no contact. For the same\nreason its `prompt` cannot hold a token such as `{first_name}` or `{{company}}`.\n            \n`format: gif` makes each image an animated GIF of `frameCount` frames (2 to 16, default 9) that each show\nfor `frameDurationMs` (20 to 2000, default 200). It needs a model whose `supportsGif` is true in the list\nresponse, and no `references`. A GIF costs more than a still: read the estimate before you turn it on.\n            \nErrors:\n            \n- `400 validation_failed`: a field is missing or not valid, the key is a reserved field, or `enabled` is\n  true. A `gif` while animated GIFs are not available, on a model without GIF support, or with references is\n  also a `400`. `error.details` names the field.\n- `404 not_found`: the campaign does not exist in this workspace.\n- `409 link_host_required`: the workspace has no tracking link host.\n- `409 image_variable_limit`: the campaign already has 5 image variables.\n- `409 variable_key_taken`: a custom, AI or image variable of the campaign already uses the key, or the key\n  is `custom_image`.\n            \nRequires Campaigns edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `campaign_images` feature on your workspace. Until it is on, calls answer 404.","operationId":"image-variables.create","parameters":[{"name":"campaignId","in":"path","description":"Id of the campaign.","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":{"description":"The variable to create.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateImageVariableRequest"}}}},"responses":{"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/ImageVariableResponse"}}}},"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"]},"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":["image_variable_limit","link_host_required","variable_key_taken"]},"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-features":["campaign_images"],"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/campaigns/{campaignId}/image-variables/{variableKey}":{"get":{"tags":["image-variables"],"summary":"Get an image variable","description":"Returns one image variable with the counts of its contact images. A `shared` variable also has its current\nimage in `sharedImage`, with a `previewUrl` that works for 1 hour.\n            \nErrors:\n            \n- `404 not_found`: the campaign or the variable does not exist in this workspace.\n            \nRequires Campaigns view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `campaign_images` feature on your workspace. Until it is on, calls answer 404.","operationId":"image-variables.get","parameters":[{"name":"campaignId","in":"path","description":"Id of the campaign.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"variableKey","in":"path","description":"Key of the image variable, such as `hero_image`.","required":true,"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/ImageVariableResponse"}}}},"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-features":["campaign_images"],"x-ken-permission":{"kind":"page","page":"campaigns","access":"view","summary":"Campaigns view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"patch":{"tags":["image-variables"],"summary":"Update an image variable","description":"Changes an image variable. Fields you leave out keep their value. Send `prompt` or `altText` as null or\nblank to clear it. `key` and `kind` never change, so sending either one is a `400`.\n            \n`enabled: true` turns on a `per_prospect` variable: Kenso then generates an image for each eligible\ncontact and charges credits for each ready image. `enabled: false` is always allowed. It stops new images and\nkeeps the ones that exist.\n            \nA change to `prompt`, `references`, `model`, `size`, `quality`, `format` or the GIF\nframes replaces the images of contacts that have no sent or queued step using the variable. Send the same fields\nto the estimate call first to see how many images that replaces and what it costs.\n            \n`format: still` clears `frameCount` and `frameDurationMs`. `format: gif` without frames takes\n9 frames at 200 ms. A GIF variable cannot move to a model without GIF support: set `format: still` first.\n            \nErrors:\n            \n- `400 validation_failed`: a field is not valid, or the body has `key` or `kind`.\n  `error.details` names the field.\n- `404 not_found`: the campaign or the variable does not exist in this workspace.\n            \nRequires Campaigns edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `campaign_images` feature on your workspace. Until it is on, calls answer 404.","operationId":"image-variables.update","parameters":[{"name":"campaignId","in":"path","description":"Id of the campaign.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"variableKey","in":"path","description":"Key of the image variable, such as `hero_image`.","required":true,"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"}}],"requestBody":{"description":"The fields to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateImageVariableRequest"}}}},"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/ImageVariableResponse"}}}},"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-features":["campaign_images"],"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-credits":[{"action":"campaign_image","pricing":"varies"}],"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}},"delete":{"tags":["image-variables"],"summary":"Delete an image variable","description":"Deletes an image variable. Returns `204`. Images Kenso already made stay. You cannot delete a variable while\na step of the campaign has its `{{key}}` token in the body or subject: remove the token first, or turn the\nvariable off with `enabled: false` instead.\n            \nErrors:\n            \n- `404 not_found`: the campaign or the variable does not exist in this workspace.\n- `409 image_variable_in_use`: a step of the campaign still uses the token.\n            \nRequires Campaigns edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `campaign_images` feature on your workspace. Until it is on, calls answer 404.","operationId":"image-variables.delete","parameters":[{"name":"campaignId","in":"path","description":"Id of the campaign.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"variableKey","in":"path","description":"Key of the image variable, such as `hero_image`.","required":true,"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":{"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","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"]},"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":["image_variable_in_use"]},"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-features":["campaign_images"],"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/campaigns/{campaignId}/image-variables/{variableKey}/estimate":{"post":{"tags":["image-variables"],"summary":"Estimate an image variable's cost","description":"Returns how many images the variable would generate now and what they would cost. Nothing is saved. To price a\nchange before you make it, send the fields you plan to change, with the same names as on `PATCH`. Fields you\nleave out use the saved values, and an empty body prices the variable as it is saved.\n            \nFor a `per_prospect` variable, `leadsNow` counts the contacts that would get an image now. It already\nincludes the `replaceCount` contacts whose current image the change would replace. `creditsNow` is\n`leadsNow` times `creditsPerImage`. A `shared` variable is one image: `creditsNow` is the price\nof that image and `creditsPerNewLead` is 0. All prices are in credits.\n            \nErrors:\n            \n- `400 validation_failed`: a field is not valid. `error.details` names the field.\n- `404 not_found`: the campaign or the variable does not exist in this workspace.\n            \nRequires Campaigns edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `campaign_images` feature on your workspace. Until it is on, calls answer 404.","operationId":"image-variables.estimate","parameters":[{"name":"campaignId","in":"path","description":"Id of the campaign.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"variableKey","in":"path","description":"Key of the image variable, such as `hero_image`.","required":true,"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"}}],"requestBody":{"description":"The fields to price. Optional.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateImageVariableRequest"}}}},"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/ImageVariableEstimateResponse"}}}},"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-features":["campaign_images"],"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/campaigns/{campaignId}/image-variables/{variableKey}/test":{"post":{"tags":["image-variables"],"summary":"Test an image variable on contacts","description":"Generates images for up to 5 contacts of a `per_prospect` variable, so you can check the result before you\nturn the variable on. The call waits for the images and returns them. Each image becomes that contact's image.\nThe test does not turn the variable on.\n            \nKenso picks contacts with no image first, then contacts whose image failed. It never picks a contact whose image\nKenso blocked. A contact whose generation failed outright is left out of the response. Kenso charges credits for\neach ready image. Each contact it picks counts toward the workspace's daily limit of image generations (100 a day,\nlower on the Free plan). When no contact is eligible, the call generates nothing and counts nothing.\n            \nErrors:\n            \n- `404 not_found`: the campaign or the variable does not exist in this workspace.\n- `409 wrong_kind`: the variable is `shared`. Set its image with the shared image call instead.\n- `429 quota_exceeded`: the workspace reached its daily limit of image generations. `Retry-After` says\n  when to try again.\n            \nRequires Campaigns edit.\n\nRate limit: 240 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `campaign_images` feature on your workspace. Until it is on, calls answer 404.","operationId":"image-variables.test","parameters":[{"name":"campaignId","in":"path","description":"Id of the campaign.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"variableKey","in":"path","description":"Key of the image variable, such as `hero_image`.","required":true,"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/ImageVariableTestResponse"}}}},"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"]},"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":["wrong_kind"]},"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"]}},"x-ken-features":["campaign_images"],"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-credits":[{"action":"campaign_image","pricing":"varies"}],"x-ken-rate-limit":{"limit":240,"windowSeconds":60,"per":"api_key"}}},"/v1/campaigns/{campaignId}/image-variables/{variableKey}/shared-image":{"post":{"tags":["image-variables"],"summary":"Set a shared image variable's image","description":"Sets the one image of a `shared` variable. Send exactly one source:\n            \n- A multipart form with a `file` field: a PNG, JPEG or WebP image of at most 10 MB.\n- A JSON body `{ \"url\": \"https://...\" }`: a public https image that Kenso downloads once.\n- A JSON body `{ \"generate\": true }`: Kenso generates the image from the variable's prompt. The call waits\n  for the image, charges credits for it and counts toward the workspace's daily limit of image generations.\n            \nReturns the variable. An upload or a URL costs nothing. If a generation fails, `sharedImage.status` is\n`failed` with its `errorCode`, and the image in use stays.\n            \nErrors:\n            \n- `400 validation_failed`: the body has no source or more than one, the file is not an allowed image, Kenso\n  could not use the image at `url`, or the variable has no prompt to generate from.\n- `404 not_found`: the campaign or the variable does not exist in this workspace.\n- `409 wrong_kind`: the variable is `per_prospect`.\n- `409 link_host_required`: the workspace has no tracking link host.\n- `409 blocked`: Kenso blocked the current image, so no source can replace it. Create a new image variable\n  instead.\n- `409` with a failure reason such as `provider_refused`: the generation saved no image.\n- `429 quota_exceeded`: a generation would pass the workspace's daily limit of image generations.\n            \nRequires Campaigns edit.\n\nRate limit: 240 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `campaign_images` feature on your workspace. Until it is on, calls answer 404.","operationId":"image-variables.set-shared-image","parameters":[{"name":"campaignId","in":"path","description":"Id of the campaign.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"variableKey","in":"path","description":"Key of the image variable, such as `hero_image`.","required":true,"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"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ImageFileFormBody"}},"application/json":{"schema":{"$ref":"#/components/schemas/SetSharedImageRequest"}}},"required":true},"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/ImageVariableResponse"}}}},"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"]},"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":["blocked","link_host_required","wrong_kind"]},"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"]}},"x-ken-features":["campaign_images"],"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-credits":[{"action":"campaign_image","pricing":"varies"}],"x-ken-rate-limit":{"limit":240,"windowSeconds":60,"per":"api_key"}}},"/v1/campaigns/{campaignId}/image-variables/{variableKey}/contacts/{contactId}/regenerate":{"post":{"tags":["image-variables"],"summary":"Regenerate a contact's image","description":"Generates a new image for one contact of a `per_prospect` variable. The call waits for the image and returns\nit, ready or failed. The contact keeps its previous image until a new one is ready. Kenso charges credits for a\nready image, and the call counts toward the workspace's daily limit of image generations.\n            \nErrors:\n            \n- `404 not_found`: the campaign, the variable or the contact does not exist in this workspace, or the\n  contact is not one Kenso makes images for in this campaign.\n- `409 wrong_kind`: the variable is `shared`.\n- `409 image_in_use`: the contact already has a sent or queued step that uses the variable, so it keeps that\n  image.\n- `409 blocked`: Kenso blocked the contact's current image. After a prompt change, Kenso can still generate\n  a new image for the contact, but this call does not replace it.\n- `409` with a failure reason such as `provider_refused`: the generation saved no image.\n- `429 quota_exceeded`: the workspace reached its daily limit of image generations.\n            \nRequires Campaigns edit.\n\nRate limit: 240 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `campaign_images` feature on your workspace. Until it is on, calls answer 404.","operationId":"image-variables.regenerate-contact","parameters":[{"name":"campaignId","in":"path","description":"Id of the campaign.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"variableKey","in":"path","description":"Key of the image variable, such as `hero_image`.","required":true,"schema":{"type":"string"}},{"name":"contactId","in":"path","description":"Id of the contact.","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/CampaignImageResponse"}}}},"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"]},"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":["blocked","image_in_use","wrong_kind"]},"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"]}},"x-ken-features":["campaign_images"],"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-credits":[{"action":"campaign_image","pricing":"varies"}],"x-ken-rate-limit":{"limit":240,"windowSeconds":60,"per":"api_key","summary":"100 requests a day per workspace (Free plan: 10 a day)","quotas":[{"policy":"campaignImageEditorGenerations","per":"workspace","limits":[{"limit":100,"windowSeconds":86400}],"plans":[{"plan":"Free","limits":[{"limit":10,"windowSeconds":86400}]}]}]}}}},"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."},"CampaignImage":{"type":"object","properties":{"imageKey":{"type":"string","description":"The image's unique 26-character key. Read the image again with `GET /v1/campaign-images/{imageKey}`."},"contactId":{"type":"integer","description":"Id of the contact the image belongs to. Omitted for an image that every contact shares.","format":"int64","nullable":true},"variableKey":{"type":"string","description":"Key of the image variable the image fills, or `custom_image` for the contact's own image. Omitted when the\nimage belongs to no current image variable.","nullable":true},"status":{"type":"string","description":"State of the image: `pending` while Kenso makes or fetches it, `ready` once it is stored, or `failed`."},"errorCode":{"type":"string","description":"Why the image failed, such as `timeout`, `not_an_image`, `too_large` or `provider_error`. Set\nwhen `status` is `failed`.","nullable":true},"errorDetail":{"type":"string","description":"A readable explanation of the failure. Set when `status` is `failed`.","nullable":true},"width":{"type":"integer","description":"Width of the image in pixels. Omitted while unknown.","format":"int32","nullable":true},"height":{"type":"integer","description":"Height of the image in pixels. Omitted while unknown.","format":"int32","nullable":true},"previewUrl":{"type":"string","description":"A link to view the ready image, valid until `previewExpiresAt`. Use it for viewing only, not inside an email.\nOmitted unless `status` is `ready`.","nullable":true},"previewExpiresAt":{"type":"string","description":"When `previewUrl` stops working, in UTC: 1 hour after the call. Omitted with `previewUrl`.","format":"date-time","nullable":true},"updatedAt":{"type":"string","description":"When the image last changed, in UTC.","format":"date-time"}},"additionalProperties":false,"description":"An image Kenso made or stored for a campaign's emails."},"CampaignImageResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/CampaignImage"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"CreateImageVariableRequest":{"required":["key","kind"],"type":"object","properties":{"key":{"type":"string","description":"The token key. Required. Kenso normalizes it to lowercase snake_case, so `Hero Image` becomes\n`hero_image`. It cannot change later."},"kind":{"type":"string","description":"Either `shared` or `per_prospect`. Required. It cannot change later."},"prompt":{"type":"string","description":"What to draw, at most 4,000 characters. Required for `per_prospect`.","nullable":true},"references":{"type":"array","items":{"type":"string"},"description":"Reference pictures: `profile_photo`, `company_logo`, `sender_logo`, `website_screenshot` or\n`custom_image`. A `shared` variable can use only `sender_logo`. Omitted is none.","nullable":true},"model":{"type":"string","description":"Id of the image model, from `models` in the list response. Defaults to `openai/gpt-image-2.6-sunburst`.","nullable":true},"size":{"type":"string","description":"Image size in pixels: `1024x1024`, `1536x1024` or `1024x1536`. Defaults to `1024x1024`.","nullable":true},"quality":{"type":"string","description":"Image quality: `low`, `medium` or `high`. Defaults to `medium`.","nullable":true},"format":{"type":"string","description":"Either `still` (the default) or `gif` for an animated GIF. A `gif` needs a model whose\n`supportsGif` is true in the list response, and no `references`.","nullable":true},"frameCount":{"type":"integer","description":"Frames of the animated GIF, 2 to 16. Defaults to 9. Ignored when `format` is `still`.","format":"int32","nullable":true},"frameDurationMs":{"type":"integer","description":"Milliseconds each GIF frame shows, 20 to 2000, rounded to 10. Defaults to 200. Ignored when `format` is\n`still`.","format":"int32","nullable":true},"spellingCheck":{"type":"boolean","description":"Whether Kenso checks the text in each image against the prompt. Defaults to true.","nullable":true},"requiredForSending":{"type":"boolean","description":"Whether a contact waits for a ready image before steps that use the token. Defaults to false.","nullable":true},"enabled":{"type":"boolean","description":"Leave it out or send false: a new variable is always off, and true is a `400`. Turn it on with\n`PATCH` after you read its estimate.","nullable":true},"altText":{"type":"string","description":"Alt text of the image in the email, at most 200 characters.","nullable":true}},"additionalProperties":false,"description":"An image variable to add to a campaign. Optional fields you leave out take their defaults."},"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."},"EstimateImageVariableRequest":{"type":"object","properties":{"prompt":{"type":"string","description":"The prompt to price. Null or blank prices the variable with no prompt.","nullable":true},"references":{"type":"array","items":{"type":"string"},"description":"The reference pictures to price.","nullable":true},"model":{"type":"string","description":"The image model to price.","nullable":true},"size":{"type":"string","description":"The image size to price.","nullable":true},"quality":{"type":"string","description":"The image quality to price.","nullable":true},"format":{"type":"string","description":"The format to price: `still` or `gif`. An animated GIF costs more than a still.","nullable":true},"frameCount":{"type":"integer","description":"The GIF frame count to price, 2 to 16. More frames cost more.","format":"int32","nullable":true},"frameDurationMs":{"type":"integer","description":"The GIF frame duration to price, 20 to 2000 milliseconds.","format":"int32","nullable":true},"spellingCheck":{"type":"boolean","description":"The spelling check setting to price.","nullable":true}},"additionalProperties":false,"description":"Image variable fields to price before you save them. Each field you leave out uses the saved value."},"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`."},"ImageFileFormBody":{"required":["file"],"type":"object","properties":{"file":{"type":"string","description":"A PNG, JPEG or WebP image, at most 10 MB.","format":"binary"}},"additionalProperties":false,"description":"The multipart body that uploads an image. A JSON body is the other way to send it."},"ImageVariable":{"type":"object","properties":{"key":{"type":"string","description":"The token key in lowercase snake_case, such as `hero_image` for the `{{hero_image}}` token."},"kind":{"type":"string","description":"Either `shared` (one image for every contact) or `per_prospect` (one image per contact)."},"prompt":{"type":"string","description":"What to draw. A `per_prospect` prompt can use contact tokens such as `{{first_name}}`. Null when the\nvariable has no prompt.","nullable":true},"references":{"type":"array","items":{"type":"string"},"description":"Pictures Kenso gives the image model with the prompt: `profile_photo`, `company_logo`,\n`sender_logo`, `website_screenshot` or `custom_image` (the contact's own image). A contact that\nlacks a picture is generated without it."},"model":{"type":"string","description":"Id of the image model, one of the `models` in the list response."},"size":{"type":"string","description":"Image size in pixels: `1024x1024`, `1536x1024` or `1024x1536`."},"quality":{"type":"string","description":"Image quality: `low`, `medium` or `high`."},"format":{"type":"string","description":"Either `still` (one image) or `gif` (an animated GIF)."},"frameCount":{"type":"integer","description":"How many frames the animated GIF has, 2 to 16. Null when `format` is `still`.","format":"int32","nullable":true},"frameDurationMs":{"type":"integer","description":"How long each GIF frame shows, in milliseconds, 20 to 2000. Null when `format` is `still`.","format":"int32","nullable":true},"spellingCheck":{"type":"boolean","description":"When true, Kenso checks the text in each image against the prompt and generates it once more if they differ."},"requiredForSending":{"type":"boolean","description":"When true, Kenso holds a contact from steps that use the token until the contact's image is ready."},"enabled":{"type":"boolean","description":"Whether a `per_prospect` variable is on. While it is on, Kenso generates an image for each eligible contact\nand charges credits for each ready image. Turning it off keeps the images that exist."},"altText":{"type":"string","description":"Alt text of the image in the email, or null for none.","nullable":true},"sharedImage":{"allOf":[{"$ref":"#/components/schemas/SharedImage"}],"description":"The current image of a `shared` variable, or the attempt that just failed. Null for a `per_prospect`\nvariable and for a `shared` one with no image yet."},"counts":{"allOf":[{"$ref":"#/components/schemas/ImageVariableCounts"}],"description":"How many contact images the variable has, by status."},"createdAt":{"type":"string","description":"When the variable was created, in UTC.","format":"date-time"},"updatedAt":{"type":"string","description":"When the variable last changed, in UTC.","format":"date-time"}},"additionalProperties":false,"description":"An image variable: a campaign's `{{key}}` image token and how Kenso makes its image. A `shared` variable\nhas one image for every contact. A `per_prospect` variable has one image per contact, which Kenso generates\nwhile the variable is on."},"ImageVariableCounts":{"type":"object","properties":{"ready":{"type":"integer","description":"Contacts whose current image is ready.","format":"int32"},"pending":{"type":"integer","description":"Images that Kenso is still generating.","format":"int32"},"failed":{"type":"integer","description":"Contacts whose current image failed.","format":"int32"}},"additionalProperties":false,"description":"Counts of a `per_prospect` variable's contact images: the current ready and failed images, and every pending one."},"ImageVariableEstimate":{"type":"object","properties":{"leadsNow":{"type":"integer","description":"Contacts that would get an image now, including the contacts whose image the change would replace. 0 for a `shared` variable.","format":"int32"},"replaceCount":{"type":"integer","description":"Of those contacts, how many have a ready image that the change would replace.","format":"int32"},"creditsPerImage":{"type":"number","description":"Estimated credits for one image.","format":"double"},"creditsNow":{"type":"number","description":"Estimated credits for the images Kenso would generate now. For a `shared` variable, the price of its one image.","format":"double"},"creditsPerNewLead":{"type":"number","description":"Estimated credits for each contact that becomes eligible later. 0 for a `shared` variable.","format":"double"}},"additionalProperties":false,"description":"What an image variable would generate now and cost. All prices are in credits."},"ImageVariableEstimateResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/ImageVariableEstimate"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"ImageVariableListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a successful call."},"data":{"type":"array","items":{"$ref":"#/components/schemas/ImageVariable"},"description":"The campaign's image variables, ordered by key."},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"}],"description":"Always one page: `hasMore` is false."},"linkHostReady":{"type":"boolean","description":"Whether the workspace has a tracking link host. Without one, you cannot create or send an image variable."},"coverage":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Counts of contacts. `leads` is how many contacts Kenso counted, and each reference name, such as\n`profile_photo`, is how many of them have that picture."},"models":{"type":"array","items":{"$ref":"#/components/schemas/ImageVariableModelOption"},"description":"The image models you can pick, with their estimated price."}},"additionalProperties":false,"description":"A campaign's image variables, with what you need to set one up."},"ImageVariableModelOption":{"type":"object","properties":{"id":{"type":"string","description":"Model id to send as `model`, such as `openai/gpt-image-2.6-sunburst`."},"displayName":{"type":"string","description":"The model's display name."},"creditsPerImage":{"type":"number","description":"Estimated credits for one `per_prospect` still image with this model in this workspace.","format":"double"},"supportsGif":{"type":"boolean","description":"Whether an image variable on this model can be an animated GIF (`format: gif`). False for every model while\nanimated GIFs are not available."}},"additionalProperties":false,"description":"An image model an image variable can use, with its estimated price."},"ImageVariableResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/ImageVariable"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"ImageVariableTest":{"type":"object","properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/CampaignImage"},"description":"One image per tested contact, ready or failed. A contact whose generation failed outright is left out."}},"additionalProperties":false,"description":"The images a test generated."},"ImageVariableTestResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/ImageVariableTest"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"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."},"SetSharedImageRequest":{"type":"object","properties":{"url":{"type":"string","description":"A public https link to a PNG, JPEG or WebP image of at most 10 MB. Kenso downloads it once.","nullable":true},"generate":{"type":"boolean","description":"True generates the image from the variable's prompt. The call waits for the image and charges credits for it.","nullable":true}},"additionalProperties":false,"description":"The JSON source of a shared image: exactly one of `url` and `generate: true`. A file upload uses a multipart form instead.","example":{"url":"https://cdn.example.com/brand/team-photo.png"}},"SharedImage":{"type":"object","properties":{"imageKey":{"type":"string","description":"Key of the image, the same as on the campaign's image routes."},"status":{"type":"string","description":"State of the image: `pending`, `ready` or `failed`."},"errorCode":{"type":"string","description":"Why the image failed, such as `provider_refused` or `spelling_mismatch`. Null unless `status` is `failed`.","nullable":true},"previewUrl":{"type":"string","description":"A link to view the image, valid until `previewExpiresAt`. Do not put it in emails or keep it.","nullable":true},"previewExpiresAt":{"type":"string","description":"When `previewUrl` stops working, in UTC, 1 hour after the call.","format":"date-time","nullable":true}},"additionalProperties":false,"description":"The one image of a `shared` image variable."},"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."},"UpdateImageVariableRequest":{"type":"object","properties":{"key":{"type":"string","description":"Cannot change. Sending it is a `400`.","nullable":true},"kind":{"type":"string","description":"Cannot change. Sending it is a `400`.","nullable":true},"prompt":{"type":"string","description":"What to draw, at most 4,000 characters. Null or blank clears it, which a `per_prospect` variable does not\nallow.","nullable":true},"references":{"type":"array","items":{"type":"string"},"description":"The full new list of reference pictures. An empty list removes them all.","nullable":true},"model":{"type":"string","description":"Id of the image model, from `models` in the list response.","nullable":true},"size":{"type":"string","description":"Image size in pixels: `1024x1024`, `1536x1024` or `1024x1536`.","nullable":true},"quality":{"type":"string","description":"Image quality: `low`, `medium` or `high`.","nullable":true},"format":{"type":"string","description":"Either `still` or `gif`. `still` clears the frame settings. `gif` needs a model whose\n`supportsGif` is true in the list response and no `references`, and takes 9 frames at 200 ms unless you\nsend them.","nullable":true},"frameCount":{"type":"integer","description":"Frames of the animated GIF, 2 to 16. Ignored on a `still` variable.","format":"int32","nullable":true},"frameDurationMs":{"type":"integer","description":"Milliseconds each GIF frame shows, 20 to 2000, rounded to 10. Ignored on a `still` variable.","format":"int32","nullable":true},"spellingCheck":{"type":"boolean","description":"Whether Kenso checks the text in each image against the prompt.","nullable":true},"requiredForSending":{"type":"boolean","description":"Whether a contact waits for a ready image before steps that use the token.","nullable":true},"enabled":{"type":"boolean","description":"True turns a `per_prospect` variable on, so Kenso generates and charges for each eligible contact's image.\nFalse is always allowed and keeps the images that exist.","nullable":true},"altText":{"type":"string","description":"Alt text of the image in the email, at most 200 characters. Null or blank clears it.","nullable":true}},"additionalProperties":false,"description":"The image variable fields to change. Fields you leave out keep their value. `key` and `kind` never change:\nsending either one is a `400`."}}}}