{"openapi":"3.0.0","paths":{"/health":{"get":{"operationId":"HealthController_health","parameters":[],"responses":{"200":{"description":""}},"tags":["Health"]}},"/v1/me":{"get":{"summary":"Describe the authenticated credential (API key or OAuth grant): scopes and accessible accounts","tags":["me"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["api_key","oauth_token"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"subject_type":{"type":"string","enum":["business","agency"]},"scopes":{"type":"array","items":{"type":"string","enum":["catalog:read","catalog:write","campaigns:read","campaigns:write","connections:read","tasks:read","tasks:write","skills:read","workflows:read","workflows:write","platform:read","platform:write","costs:write"]}},"account_required":{"type":"boolean"},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"nullable":true,"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["object","id","subject_type","scopes","account_required","accounts"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/accounts":{"get":{"summary":"List the accounts this API key can operate on","tags":["accounts"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["account"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"nullable":true,"type":"string"},"connections":{"nullable":true,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["object","id","name","connections"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/connections":{"get":{"summary":"List the authenticated account's connections","tags":["connections"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the connection name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"type","in":"query","schema":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/connections/{id}":{"get":{"tags":["connections"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/countries":{"get":{"summary":"List Amazon marketplace countries","tags":["countries"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"code","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/countries/{id}":{"get":{"tags":["countries"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-brands":{"get":{"summary":"List the brands present in the authenticated account's catalog","tags":["product-brands"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the brand name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-brands/{id}":{"get":{"tags":["product-brands"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/products":{"get":{"summary":"List the authenticated account's products","tags":["products"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the product title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"brand","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/products/{id}":{"get":{"tags":["products"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-seller-products":{"get":{"summary":"List the authenticated account's Amazon seller products","tags":["amazon-seller-products"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the listing title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"brand","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"sellerCentralInfo":{},"catalogPublicInfo":{},"pricing":{},"buyboxB2C":{},"buyboxB2B":{},"fbaInventory":{},"aplusContent":{},"competitivePriceSummary":{},"suppressed":{},"fbaLocalStock":{},"salesRanks":{},"amazonStatus":{"nullable":true,"type":"string"},"publicParentSKU":{"nullable":true,"type":"string"},"publicParentASIN":{"nullable":true,"type":"string"},"publicIsParentASIN":{"nullable":true,"type":"boolean"},"backendParentSKU":{"nullable":true,"type":"string"},"backendParentASIN":{"nullable":true,"type":"string"},"backendIsParentASIN":{"nullable":true,"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","amazonStatus","publicParentSKU","publicParentASIN","publicIsParentASIN","backendParentSKU","backendParentASIN","backendIsParentASIN","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-seller-products/{id}":{"get":{"tags":["amazon-seller-products"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"sellerCentralInfo":{},"catalogPublicInfo":{},"pricing":{},"buyboxB2C":{},"buyboxB2B":{},"fbaInventory":{},"aplusContent":{},"competitivePriceSummary":{},"suppressed":{},"fbaLocalStock":{},"salesRanks":{},"amazonStatus":{"nullable":true,"type":"string"},"publicParentSKU":{"nullable":true,"type":"string"},"publicParentASIN":{"nullable":true,"type":"string"},"publicIsParentASIN":{"nullable":true,"type":"boolean"},"backendParentSKU":{"nullable":true,"type":"string"},"backendParentASIN":{"nullable":true,"type":"string"},"backendIsParentASIN":{"nullable":true,"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","amazonStatus","publicParentSKU","publicParentASIN","publicIsParentASIN","backendParentSKU","backendParentASIN","backendIsParentASIN","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-vendor-products":{"get":{"summary":"List the authenticated account's Amazon vendor products","tags":["amazon-vendor-products"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the listing title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"brand","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"vendorCentralInfo":{},"catalogPublicInfo":{},"aplusContent":{},"inventory":{},"salesRanks":{},"customerFeedback":{},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-vendor-products/{id}":{"get":{"tags":["amazon-vendor-products"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"vendorCentralInfo":{},"catalogPublicInfo":{},"aplusContent":{},"inventory":{},"salesRanks":{},"customerFeedback":{},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-advertising-products":{"get":{"summary":"List the authenticated account's Amazon advertising products","tags":["amazon-advertising-products"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the listing title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"brand","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"availability":{"nullable":true,"type":"string","enum":["IN_STOCK","IN_STOCK_SCARCE","OUT_OF_STOCK","PREORDER","LEADTIME","AVAILABLE_DATE"]},"eligibilityStatus":{"nullable":true,"type":"string","enum":["ELIGIBLE","INELIGIBLE"]},"ineligibilityCodes":{"type":"array","items":{"type":"string"}},"ineligibilityReasons":{"type":"array","items":{"type":"string"}},"basisPrice":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"],"additionalProperties":false},"bestSellerRank":{"nullable":true,"type":"string"},"firstAvailabilityDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"categoryName":{"nullable":true,"type":"string"},"brandName":{"nullable":true,"type":"string"},"variationList":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","availability","eligibilityStatus","ineligibilityCodes","ineligibilityReasons","basisPrice","bestSellerRank","firstAvailabilityDate","categoryName","brandName","variationList","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-advertising-products/{id}":{"get":{"tags":["amazon-advertising-products"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"availability":{"nullable":true,"type":"string","enum":["IN_STOCK","IN_STOCK_SCARCE","OUT_OF_STOCK","PREORDER","LEADTIME","AVAILABLE_DATE"]},"eligibilityStatus":{"nullable":true,"type":"string","enum":["ELIGIBLE","INELIGIBLE"]},"ineligibilityCodes":{"type":"array","items":{"type":"string"}},"ineligibilityReasons":{"type":"array","items":{"type":"string"}},"basisPrice":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"],"additionalProperties":false},"bestSellerRank":{"nullable":true,"type":"string"},"firstAvailabilityDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"categoryName":{"nullable":true,"type":"string"},"brandName":{"nullable":true,"type":"string"},"variationList":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","availability","eligibilityStatus","ineligibilityCodes","ineligibilityReasons","basisPrice","bestSellerRank","firstAvailabilityDate","categoryName","brandName","variationList","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/seller-product-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window, grouped by ASIN + SKU + connection + country + currency (the same ASIN sells in several marketplaces with different prices and currencies). Unlike the rest of the API, this resource paginates with `limit`/`offset` (an aggregated row has no id to use as a cursor) and `has_more` tells whether another page follows. Monetary amounts are decimal strings. `sessions`, `page_views`, `buy_box_percentage`, `conversion_rate` and `rank` are `null`, never `0`, when Amazon did not report them: its traffic report only covers products with activity. `conversion_rate` is `orders / sessions` here, not `orders / clicks` as in `campaign_metrics`. The economics block (`referral_fee`, `fba_fulfilment_fee`, `storage_fee`, `other_fees`, `amazon_fees`, `net_sales`, `net_units`, `margin_before_ads`, `refunded_sales`, `refunded_units`) comes from Amazon Data Kiosk and has three caveats: every amount excludes VAT, as `sales` does, but it comes from a different Amazon source, so `net_sales` does not reconcile exactly with `sales` minus refunds; storage fees are booked on a single day of the month, so read margins over at least a month; and refunds are booked on the refund date, not the sale date. It is `null` when there is no economics data for the product in the window (it lands 48-72 h late). No field in it includes advertising: take ad spend from the advertising metrics. For that reason `margin_before_ads` is higher than the product margin shown in the Epinium app, which also subtracts the ad spend Amazon attributes to the product. With `group_by`, rows are aggregated across products (see the parameter): sums are summed, `stock` is the sum of the latest stock of each product, `days_of_coverage` is recomputed on the aggregates (stock summed over the products that reported it, units over all of them), `buy_box_percentage` and `b2b_buy_box_percentage` are weighted by page views, and `rank`, `price` and `fulfillment_channel` are `null`. `total_count` then counts groups, or group-periods when `granularity` is not `total`.","summary":"Seller Central sales and traffic per product, from the account's report history","tags":["seller-product-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`), and the credits scale with the groups returned, not with the number of products. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter. `cluster` gives one row per product cluster (the `clusters` resource), with its id in `cluster` and its name in `cluster_name`. A product in several clusters counts in full in each of them, so the cluster rows do NOT add up to the account total, and products in no cluster are left out. It combines with `connection` and `country`, and with the `cluster` filter to choose which clusters come back.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country","cluster"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country","cluster"]}}]}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"product","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`.","schema":{"type":"string","pattern":"^[A-Z0-9]{10}$"}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["sales","units","orders","sessions","page_views","rank","conversion_rate","net_sales","amazon_fees","margin_before_ads","days_of_coverage","b2b_sales"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["seller_product_metrics"]},"product":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"nullable":true,"type":"string"},"sku":{"nullable":true,"type":"string"},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"cluster":{"nullable":true,"description":"Product cluster of the row, only with `group_by=cluster`; `null` otherwise.","type":"string","pattern":"^[a-f0-9]{24}$"},"cluster_name":{"nullable":true,"description":"Name of the product cluster, only with `group_by=cluster`; `null` otherwise.","type":"string"},"currency":{"type":"string"},"date":{"type":"string"},"sales":{"type":"string","description":"Product sales excluding VAT: the item price of each order line minus the VAT Amazon itemizes on it. Lines where Amazon does not itemize VAT (pending orders, some marketplaces) count at the price charged. Refunds are not deducted."},"units":{"type":"number"},"orders":{"type":"number"},"sessions":{"nullable":true,"type":"number"},"page_views":{"nullable":true,"type":"number"},"buy_box_percentage":{"nullable":true,"description":"Share of page views that showed your offer in the Buy Box, from 0 to 100 as Amazon reports it (not a fraction), weighted by page views over the window. `null` when Amazon did not report it.","type":"number"},"conversion_rate":{"nullable":true,"description":"Conversion rate (CVR): orders per session as a fraction (0.29 = 29%). Not the advertising conversion rate, which is orders per click. `null` when no sessions were reported.","type":"number"},"rank":{"nullable":true,"description":"Best Seller Rank (BSR): the median rank over the window, lower is better, with no category. The category comes with `expand=salesRanks` on `amazon_seller_products`. `null` when Amazon did not report it, and with `group_by`.","type":"number"},"referral_fee":{"nullable":true,"description":"Amazon referral fee, excluding VAT.","type":"string"},"fba_fulfilment_fee":{"nullable":true,"description":"FBA fulfilment fee, excluding VAT.","type":"string"},"storage_fee":{"nullable":true,"description":"FBA storage fees (monthly, aged inventory and surcharges), excluding VAT. Amazon books them on a single day of the month, so a daily row or a window shorter than a month over- or under-states it.","type":"string"},"other_fees":{"nullable":true,"description":"Every other Amazon fee, excluding VAT. Can be negative: it includes refunded commissions and FBA inventory reimbursements.","type":"string"},"amazon_fees":{"nullable":true,"description":"Sum of the four fees above: what Amazon charged for the product, excluding VAT. Advertising is NOT included.","type":"string"},"net_sales":{"nullable":true,"description":"Product sales excluding VAT and net of refunds, from Amazon economics data. It comes from a different Amazon source than `sales`, so the two do not reconcile exactly. Refunds count on the refund date, not on the date of the original sale. Shipping charged to the buyer is not included. Can be negative when refunds of earlier sales exceed the sales of the window.","type":"string"},"net_units":{"nullable":true,"description":"Units ordered minus units refunded.","type":"number"},"margin_before_ads":{"nullable":true,"description":"`net_sales - amazon_fees`, excluding VAT: the margin before advertising and before product cost (COGS). Not a profit figure. Subtract the ad spend from the advertising metrics to get the margin after ads.","type":"string"},"breakeven_acos":{"nullable":true,"description":"The advertising cost of sale (ACoS) above which this product stops being profitable before any other cost: `(margin_before_ads - product cost * net_units) / net_sales`, as a fraction (0.332 = 33.2%), not a percentage. Can be negative (already losing money before advertising) or above 1. `null` when there is no product cost on file, no economics data for the window, the cost currency does not match `currency` (this resource does not convert currencies), or the account's plan does not include product cost (Business and Master only).","type":"number"},"refunded_sales":{"nullable":true,"description":"Refunded product sales, excluding VAT. Booked on the refund date, not on the date of the original sale.","type":"string"},"refunded_units":{"nullable":true,"description":"Refunded units, booked on the refund date, not on the date of the original sale.","type":"number"},"stock":{"nullable":true,"description":"Latest stock reported in the window, not a sum. With `group_by`, the sum of each product's latest value when `country` is one of the dimensions, and `null` otherwise: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. For FBA it is everything Amazon holds for the SKU, including inbound, reserved and unfulfillable units; for FBM it is the quantity set on the listing.","type":"number"},"fulfillment_channel":{"nullable":true,"description":"`FBA` or `FBM` on the last day of the window (a SKU can switch channels). `null` with `group_by`.","type":"string"},"price":{"nullable":true,"description":"Latest listing price in the window, as the buyer sees it (VAT included where it applies). `null` with `group_by`.","type":"string"},"days_of_coverage":{"nullable":true,"description":"Days the current stock lasts at the pace of the window: `stock / (units / days in the window)`. The days are those of the requested window, not only the days with sales. `null` with any `granularity` other than `total`, with a `group_by` that does not include `country` (see `stock`), when the product sold nothing in the window, or when no stock was reported. For FBA it counts all units Amazon holds, not only the sellable ones.","type":"number"},"b2b_sales":{"nullable":true,"description":"Amazon Business (B2B) sales, VAT included where it applies. It comes from a different Amazon report than `sales`, which excludes VAT, so it is not a strict subset of it.","type":"string"},"b2b_units":{"nullable":true,"description":"Amazon Business (B2B) units, a subset of `units`.","type":"number"},"b2b_order_items":{"nullable":true,"description":"Amazon Business (B2B) order items. Counts order lines, not orders.","type":"number"},"b2b_sessions":{"nullable":true,"description":"Amazon Business (B2B) sessions.","type":"number"},"b2b_page_views":{"nullable":true,"description":"Amazon Business (B2B) page views.","type":"number"},"b2b_buy_box_percentage":{"nullable":true,"description":"Amazon Business (B2B) buy box percentage, 0-100 as Amazon reports it, weighted by B2B page views over the window (the share of B2B page views that showed your offer in the buy box). `null` without B2B page views.","type":"number"}},"required":["object","product","asin","sku","connection","country","cluster","cluster_name","currency","sales","units","orders","sessions","page_views","buy_box_percentage","conversion_rate","rank","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","amazon_fees","net_sales","net_units","margin_before_ads","breakeven_acos","refunded_sales","refunded_units","stock","fulfillment_channel","price","days_of_coverage","b2b_sales","b2b_units","b2b_order_items","b2b_sessions","b2b_page_views","b2b_buy_box_percentage"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/vendor-product-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window, grouped by ASIN + connection + country + currency (the same ASIN sells in several marketplaces with different prices and currencies; the SKU is not part of the key here, unlike `seller_product_metrics`). Unlike the rest of the API, this resource paginates with `limit`/`offset` (an aggregated row has no id to use as a cursor) and `has_more` tells whether another page follows. Monetary amounts are decimal strings. There is deliberately NO single `sales` field: Vendor Central has two business models and Amazon does not report them symmetrically. Manufacturing (Amazon makes the product under licence) reports ordered, shipped and net received, while sourcing (you sell wholesale to Amazon) reports only shipped and net received. Read the pair that matches how you sell. Vendor has no sessions or conversion rate at all; `glance_views` is the traffic metric, and it is `null`, never `0`, when Amazon did not report it, as are `rank` and both `*_sellable_units`. The `*_sellable_units` fields are the latest inventory snapshot in the window, not a sum. With `group_by`, rows are aggregated across products (see the parameter): sums are summed, the snapshot fields (both `*_sellable_units` and the other levels read on the last day of the window with data) are the sum of the latest value of each product, `days_of_coverage` is recomputed on the aggregates (stock summed over the products that reported it, units over all of them), and `rank`, `sourcing_lead_time_days` and the sourcing rates are `null`. `total_count` then counts groups, or group-periods when `granularity` is not `total`.","summary":"Vendor Central sales per product, split by manufacturing and sourcing, from the account's report history","tags":["vendor-product-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`), and the credits scale with the groups returned, not with the number of products. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter. `cluster` gives one row per product cluster (the `clusters` resource), with its id in `cluster` and its name in `cluster_name`. A product in several clusters counts in full in each of them, so the cluster rows do NOT add up to the account total, and products in no cluster are left out. It combines with `connection` and `country`, and with the `cluster` filter to choose which clusters come back.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country","cluster"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country","cluster"]}}]}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"product","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`.","schema":{"type":"string","pattern":"^[A-Z0-9]{10}$"}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["units","glance_views","rank","manufacturing_ordered_sales","manufacturing_ordered_units","manufacturing_shipped_sales","manufacturing_shipped_units","manufacturing_shipped_cogs","manufacturing_net_received_sales","manufacturing_net_received_units","sourcing_shipped_sales","sourcing_shipped_units","sourcing_shipped_cogs","sourcing_net_received_sales","sourcing_net_received_units","sourcing_customer_returns","manufacturing_customer_returns","sourcing_confirmed_units","days_of_coverage"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["vendor_product_metrics"]},"product":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"nullable":true,"type":"string"},"sku":{"nullable":true,"type":"string"},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"cluster":{"nullable":true,"description":"Product cluster of the row, only with `group_by=cluster`; `null` otherwise.","type":"string","pattern":"^[a-f0-9]{24}$"},"cluster_name":{"nullable":true,"description":"Name of the product cluster, only with `group_by=cluster`; `null` otherwise.","type":"string"},"currency":{"type":"string"},"date":{"type":"string"},"units":{"type":"number"},"manufacturing_ordered_sales":{"type":"string"},"manufacturing_ordered_units":{"type":"number"},"manufacturing_shipped_sales":{"type":"string"},"manufacturing_shipped_units":{"type":"number"},"manufacturing_shipped_cogs":{"type":"string"},"manufacturing_net_received_sales":{"type":"string"},"manufacturing_net_received_units":{"type":"number"},"sourcing_shipped_sales":{"type":"string"},"sourcing_shipped_units":{"type":"number"},"sourcing_shipped_cogs":{"type":"string"},"sourcing_net_received_sales":{"type":"string"},"sourcing_net_received_units":{"type":"number"},"glance_views":{"nullable":true,"type":"number"},"manufacturing_sellable_units":{"nullable":true,"type":"number"},"sourcing_sellable_units":{"nullable":true,"type":"number"},"rank":{"nullable":true,"description":"Best Seller Rank (BSR): the median rank over the window, lower is better, with no category. The category comes with `expand=salesRanks` on `amazon_vendor_products`. `null` when Amazon did not report it, and with `group_by`.","type":"number"},"sourcing_customer_returns":{"nullable":true,"description":"Units returned by customers, sourcing view, summed over the window.","type":"number"},"manufacturing_customer_returns":{"nullable":true,"description":"Units returned by customers, manufacturing view, summed over the window.","type":"number"},"manufacturing_unfilled_ordered_units":{"nullable":true,"description":"Units ordered (or pre-ordered) by customers that have not shipped yet, on the last day of the window with data. A level, not a sum. With `group_by`, the sum of each product's latest value. Manufacturing only: Amazon does not report it for sourcing.","type":"number"},"sourcing_confirmed_units":{"nullable":true,"description":"Purchase order units the vendor confirmed to ship to Amazon, summed over the window.","type":"number"},"sourcing_open_po_units":{"nullable":true,"description":"Units in open purchase orders (confirmed, not yet received) on the last day of the window with data. A level, not a sum. With `group_by`, the sum of each product's latest value.","type":"number"},"sourcing_most_recent_submitted_units":{"nullable":true,"description":"Units Amazon ordered in the most recent purchase orders of the week, on the last day of the window with data.","type":"number"},"sourcing_received_fill_rate":{"nullable":true,"description":"Received units / confirmed units, as a fraction (0.95 = 95%), procurable ASINs only. Average of Amazon's daily rate over the window. `null` with `group_by`: Amazon reports the rate without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_vendor_confirmation_rate":{"nullable":true,"description":"Confirmed units / units Amazon asked for, as a fraction, procurable ASINs only. Average of Amazon's daily rate over the window. `null` with `group_by`: Amazon reports the rate without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_lead_time_days":{"nullable":true,"description":"Days from the purchase order to the inventory arriving at an Amazon fulfilment centre. Average over the window. `null` with `group_by`: Amazon reports the average without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_procurable_oos_rate":{"nullable":true,"description":"Share of glance views that found the product out of stock, procurable ASINs only, as a fraction. Average of Amazon's daily rate. `null` with `group_by`: Amazon reports the rate without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_sell_through_rate":{"nullable":true,"description":"(Shipped units - customer returns) / (sellable on-hand + net received units), as a fraction. Average of Amazon's daily rate. `null` with `group_by`: Amazon reports the rate without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_sourceable_oos_rate":{"nullable":true,"description":"Share of glance views that found the product out of stock, among ASINs with a vendor able to supply them, as a fraction. Average of Amazon's daily rate. `null` with `group_by`: Amazon reports the rate without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_aged_90_plus_units":{"nullable":true,"description":"Sellable units that have been 90 days or more in Amazon's warehouses, on the last day of the window with data.","type":"number"},"sourcing_unsellable_on_hand_units":{"nullable":true,"description":"Unsellable units in Amazon's fulfilment centres, on the last day of the window with data.","type":"number"},"sourcing_sellable_in_transit_units":{"nullable":true,"description":"Sellable units in transit, on the last day of the window with data.","type":"number"},"sourcing_unsellable_in_transit_units":{"nullable":true,"description":"Unsellable units in transit, on the last day of the window with data.","type":"number"},"days_of_coverage":{"nullable":true,"description":"Days the current stock lasts at the pace of the window: `sourcing_sellable_units` (or `manufacturing_sellable_units` if there is none) / (`units` / days in the window). The days are those of the requested window. `null` with any `granularity` other than `total`, when the product sold nothing in the window, or when no stock was reported, which today is always the case for manufacturing-only vendors.","type":"number"}},"required":["object","product","asin","sku","connection","country","cluster","cluster_name","currency","units","manufacturing_ordered_sales","manufacturing_ordered_units","manufacturing_shipped_sales","manufacturing_shipped_units","manufacturing_shipped_cogs","manufacturing_net_received_sales","manufacturing_net_received_units","sourcing_shipped_sales","sourcing_shipped_units","sourcing_shipped_cogs","sourcing_net_received_sales","sourcing_net_received_units","glance_views","manufacturing_sellable_units","sourcing_sellable_units","rank","sourcing_customer_returns","manufacturing_customer_returns","manufacturing_unfilled_ordered_units","sourcing_confirmed_units","sourcing_open_po_units","sourcing_most_recent_submitted_units","sourcing_received_fill_rate","sourcing_vendor_confirmation_rate","sourcing_lead_time_days","sourcing_procurable_oos_rate","sourcing_sell_through_rate","sourcing_sourceable_oos_rate","sourcing_aged_90_plus_units","sourcing_unsellable_on_hand_units","sourcing_sellable_in_transit_units","sourcing_unsellable_in_transit_units","days_of_coverage"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/cascade":{"get":{"description":"Same calculation as the \"Cascada del periodo\" chart in Rentabilidad: `net sales - fees/logistics - advertising - product cost = contribution margin`, with the previous period of equal length for comparison. Unlike every other resource in this API, amounts ARE converted: `currency` is a required parameter, and every amount in the response lands in it using the daily rate from `fx_rates_daily` (a day without a rate falls back to an approximate one, never an error). Free and Guru plans receive the same shape with `cogs`/`product_cost` always `0` and `includes_product_cost: false` - see that field before reading those as \"no cost\", they mean \"not on this plan\". `connection` and `country` restrict to a single sales connection/marketplace; without them, every Amazon Seller/Vendor connection the credential can read is summed. A `connection` outside the ones this credential can read comes back as an empty cascade, not an error - same criterion as every other resource in this API.","summary":"Waterfall P&L for the period: net sales minus fees, advertising and product cost","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"granularity","in":"query","description":"`month` (default) returns one row per calendar month. `day` returns one row per day, capped at 366 days.","schema":{"default":"month","type":"string","enum":["month","day"]}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_cascade"]},"currency":{"type":"string"},"includes_product_cost":{"type":"boolean","description":"Whether `cogs`/`product_cost` reflect real product cost. `false` on Free/Guru plans: those amounts are always `0` there, not because nothing was spent but because the plan does not include product cost. Upgrade to Business to see it."},"months":{"type":"array","items":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."},"month":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"partial":{"type":"boolean","description":"Current month, trimmed by the window, or closed less than 5 days ago: some charges (storage, late refunds) may still be missing."}},"required":["categories","sections","month","partial"],"additionalProperties":false}},"periods":{"type":"array","items":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."},"period":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}$"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}],"description":"`YYYY-MM` with `granularity=month`, `YYYY-MM-DD` with `granularity=day`."},"partial":{"type":"boolean"},"advertising":{"description":"Breakdown of the `ads` category by platform and native line. Their amounts sum exactly to `categories.ads`.","type":"array","items":{"type":"object","properties":{"ad_platform":{"type":"string","enum":["amazon_ads"]},"line":{"type":"string","enum":["ordered_product_sales","refunded_product_sales","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","vendor_sales","sp_spend","sb_spend","sd_spend","cogs","unsellable_returns","own_shipping"]},"amount":{"type":"number"}},"required":["ad_platform","line","amount"],"additionalProperties":false}}},"required":["categories","sections","period","partial"],"additionalProperties":false}},"storage_is_monthly":{"type":"boolean","description":"With `granularity=day`, Amazon still books storage fees on a single day of the month: `true` warns that a daily row or a short window over- or under-states it."},"totals":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."}},"required":["categories","sections"],"additionalProperties":false},"previous_totals":{"nullable":true,"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."}},"required":["categories","sections"],"additionalProperties":false},"previous_periods":{"nullable":true,"type":"array","items":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."},"period":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}$"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}],"description":"`YYYY-MM` with `granularity=month`, `YYYY-MM-DD` with `granularity=day`."},"partial":{"type":"boolean"},"advertising":{"description":"Breakdown of the `ads` category by platform and native line. Their amounts sum exactly to `categories.ads`.","type":"array","items":{"type":"object","properties":{"ad_platform":{"type":"string","enum":["amazon_ads"]},"line":{"type":"string","enum":["ordered_product_sales","refunded_product_sales","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","vendor_sales","sp_spend","sb_spend","sd_spend","cogs","unsellable_returns","own_shipping"]},"amount":{"type":"number"}},"required":["ad_platform","line","amount"],"additionalProperties":false}}},"required":["categories","sections","period","partial"],"additionalProperties":false}},"coverage":{"nullable":true,"description":"`null` when the window has no sales.","type":"object","properties":{"covered_sales":{"type":"number","description":"Gross sales of the window that have product cost recorded."},"total_sales":{"type":"number","description":"Gross sales of the whole window."}},"required":["covered_sales","total_sales"],"additionalProperties":false}},"required":["object","currency","includes_product_cost","months","periods","storage_is_monthly","totals","previous_totals","previous_periods","coverage"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/products":{"get":{"description":"Same per-product breakdown as the \"Margen por producto\" table in Rentabilidad, one row per catalog product plus an \"unassigned\" row (`product: null`) for sales pnl_lines could not match. Same currency-conversion exception as `/v1/pnl/cascade`: `currency` is required and every amount lands in it. Paginates with `limit`/`offset`, not a cursor - rows are aggregates, not records with an id. `order_by` picks the sort field (default `netSales`); `search` matches the catalog title, then filters by the matched SKUs/ASINs. Free and Guru plans receive every row with `cogs`/`product_cost` at `0` and `includes_product_cost: false`. A `connection` outside the ones this credential can read comes back as an empty list, not an error.","summary":"P&L with product cost per product, paginated and sortable","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"search","in":"query","description":"Case-insensitive substring match over the product title. Resolved against the catalog, then matched by SKU/ASIN - a product with no catalog match cannot be found this way.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","description":"Page size. Paginate with `offset`, not a cursor: these rows are aggregates over the window, not records with an id.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order_by","in":"query","description":"Field to sort by: `netSales` (default), `contributionMargin`, `marginPct`, `coverage`, a P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`) or a section (`revenue`, `fees_logistics`, `advertising`, `product_cost`).","schema":{"default":"netSales","type":"string","enum":["netSales","contributionMargin","marginPct","coverage","sales","refunds","commissions","logistics","storage","other_fees","ads","cogs","revenue","fees_logistics","advertising","product_cost"]}},{"name":"order","in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_product"]},"product":{"nullable":true,"description":"FK to `/v1/products`. `null` for the \"unassigned\" row: sales pnl_lines could not match to a catalog product.","type":"string","pattern":"^[a-f0-9]{24}$"},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"sku":{"nullable":true,"description":"SKU on Seller, ASIN on Vendor. `null` for the \"unassigned\" row.","type":"string"},"title":{"nullable":true,"type":"string"},"image":{"nullable":true,"type":"string"},"amounts":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."}},"required":["categories","sections"],"additionalProperties":false},"contribution_margin":{"type":"number","description":"Sum of every section: `revenue + fees_logistics + advertising + product_cost`."},"margin_pct":{"type":"number","description":"contribution_margin / net sales, as a fraction (0.25 = 25%). `0` when net sales are `0` for the window, not a real 0% margin."},"coverage":{"nullable":true,"description":"`null` when the product has no sales in the window.","type":"object","properties":{"covered_sales":{"type":"number","description":"Gross sales of the window that have product cost recorded."},"total_sales":{"type":"number","description":"Gross sales of the whole window."}},"required":["covered_sales","total_sales"],"additionalProperties":false},"previous":{"nullable":true,"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."}},"required":["categories","sections"],"additionalProperties":false}},"required":["object","product","connection","country","sku","title","image","amounts","contribution_margin","margin_pct","coverage","previous"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"currency":{"type":"string"},"includes_product_cost":{"type":"boolean","description":"Same meaning as on `/v1/pnl/cascade`: `false` on Free/Guru plans, where `cogs`/`product_cost` are always `0` on every row."}},"required":["object","data","has_more","currency","includes_product_cost"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/products/{id}":{"get":{"description":"Same ficha as the product margin section in Rentabilidad: one row per month, with the breakdown by native P&L line (e.g. `referral_fee`, `fba_fulfilment_fee`, `cogs`) inside each category. Scoped to the product's own sales connection and country, not to a `connection`/`country` filter - there is none here, the id already picks the product. Same currency-conversion exception as `/v1/pnl/cascade`. `404` when `id` does not exist, is not a catalog product (seller/vendor) or falls outside the connections this credential can read - never partial data for a product you cannot see. Free and Guru plans receive the same shape with `cogs`/`product_cost` always `0` and `includes_product_cost: false`.","summary":"P&L with product cost for one product, by month and native line","tags":["pnl"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_product_detail"]},"includes_product_cost":{"type":"boolean","description":"Same meaning as on `/v1/pnl/cascade`: `false` on Free/Guru plans, where `cogs`/`product_cost` are always `0`."},"months":{"type":"array","items":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."},"month":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"partial":{"type":"boolean","description":"Current month, trimmed by the window, or closed less than 5 days ago: some charges (storage, late refunds) may still be missing."},"lines":{"type":"object","properties":{"ordered_product_sales":{"type":"number"},"refunded_product_sales":{"type":"number"},"referral_fee":{"type":"number"},"fba_fulfilment_fee":{"type":"number"},"storage_fee":{"type":"number"},"other_fees":{"type":"number"},"vendor_sales":{"type":"number"},"sp_spend":{"type":"number"},"sb_spend":{"type":"number"},"sd_spend":{"type":"number"},"cogs":{"type":"number"},"unsellable_returns":{"type":"number"},"own_shipping":{"type":"number"}},"required":["ordered_product_sales","refunded_product_sales","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","vendor_sales","sp_spend","sb_spend","sd_spend","cogs","unsellable_returns","own_shipping"],"additionalProperties":false}},"required":["categories","sections","month","partial","lines"],"additionalProperties":false}},"totals":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."},"lines":{"type":"object","properties":{"ordered_product_sales":{"type":"number"},"refunded_product_sales":{"type":"number"},"referral_fee":{"type":"number"},"fba_fulfilment_fee":{"type":"number"},"storage_fee":{"type":"number"},"other_fees":{"type":"number"},"vendor_sales":{"type":"number"},"sp_spend":{"type":"number"},"sb_spend":{"type":"number"},"sd_spend":{"type":"number"},"cogs":{"type":"number"},"unsellable_returns":{"type":"number"},"own_shipping":{"type":"number"}},"required":["ordered_product_sales","refunded_product_sales","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","vendor_sales","sp_spend","sb_spend","sd_spend","cogs","unsellable_returns","own_shipping"],"additionalProperties":false,"description":"Amount per native P&L line (e.g. `referral_fee`, `fba_fulfilment_fee`, `cogs`). Each category is the sum of its lines."}},"required":["categories","sections","lines"],"additionalProperties":false},"previous_totals":{"nullable":true,"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."},"lines":{"type":"object","properties":{"ordered_product_sales":{"type":"number"},"refunded_product_sales":{"type":"number"},"referral_fee":{"type":"number"},"fba_fulfilment_fee":{"type":"number"},"storage_fee":{"type":"number"},"other_fees":{"type":"number"},"vendor_sales":{"type":"number"},"sp_spend":{"type":"number"},"sb_spend":{"type":"number"},"sd_spend":{"type":"number"},"cogs":{"type":"number"},"unsellable_returns":{"type":"number"},"own_shipping":{"type":"number"}},"required":["ordered_product_sales","refunded_product_sales","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","vendor_sales","sp_spend","sb_spend","sd_spend","cogs","unsellable_returns","own_shipping"],"additionalProperties":false,"description":"Amount per native P&L line (e.g. `referral_fee`, `fba_fulfilment_fee`, `cogs`). Each category is the sum of its lines."}},"required":["categories","sections","lines"],"additionalProperties":false},"coverage":{"nullable":true,"description":"`null` when the product has no sales in the window.","type":"object","properties":{"covered_sales":{"type":"number","description":"Gross sales of the window that have product cost recorded."},"total_sales":{"type":"number","description":"Gross sales of the whole window."}},"required":["covered_sales","total_sales"],"additionalProperties":false},"currency":{"type":"string"}},"required":["object","includes_product_cost","months","totals","previous_totals","coverage","currency"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/channels":{"get":{"description":"Same per-connection breakdown as the channel card in Rentabilidad: one row per sales connection (Amazon Seller or Vendor), ordered by net sales. No `limit`/`offset`: the row count is bounded by the sales connections this credential can read, not by catalog size. Same currency-conversion exception as `/v1/pnl/cascade`. Free and Guru plans receive every row with `cogs`/`product_cost` at `0` and `includes_product_cost: false`. A `connection` outside the ones this credential can read comes back as an empty list, not an error.","summary":"P&L with product cost per sales connection","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_channel"]},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"channel":{"type":"string","enum":["seller","vendor"]},"platform":{"type":"string","description":"Sales platform of the connection. Always `amazon` today: Shopify and WooCommerce do not feed this P&L yet."},"amounts":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."}},"required":["categories","sections"],"additionalProperties":false},"contribution_margin":{"type":"number","description":"Sum of every section: `revenue + fees_logistics + advertising + product_cost`."},"margin_pct":{"type":"number","description":"contribution_margin / net sales, as a fraction (0.25 = 25%). `0` when net sales are `0` for the window, not a real 0% margin."},"previous":{"nullable":true,"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"}},"required":["sales","refunds","commissions","logistics","storage","other_fees","ads","cogs"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `commissions`, `logistics`, `storage`, `other_fees`, `ads`, `cogs`), signed: revenue positive, costs negative. `cogs` is `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`. Each is the sum of its categories."}},"required":["categories","sections"],"additionalProperties":false}},"required":["object","connection","channel","platform","amounts","contribution_margin","margin_pct","previous"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"currency":{"type":"string"},"includes_product_cost":{"type":"boolean","description":"Same meaning as on `/v1/pnl/cascade`: `false` on Free/Guru plans, where `cogs`/`product_cost` are always `0` on every row."}},"required":["object","data","has_more","currency","includes_product_cost"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/ads-matrix":{"get":{"description":"Same breakdown as the advertising matrix in the channel card of Rentabilidad: one row per sales connection and ad platform combination (only `amazon_ads` exists today). No `limit`/`offset`, same reasoning as `/v1/pnl/channels`. Same currency-conversion exception as `/v1/pnl/cascade`. Not plan-gated: advertising spend is part of the pre-COGS P&L every plan already sees via `seller_product_metrics`/`vendor_product_metrics`, so there is no `includes_product_cost` field here. A `connection` outside the ones this credential can read comes back as an empty list, not an error.","summary":"Advertising spend per sales connection and ad platform, against that connection's net sales","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_ad_spend"]},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_platform":{"type":"string","enum":["amazon_ads"]},"amount":{"type":"number","description":"Advertising spend of this connection and platform in the window, negative."},"pct_of_net_sales":{"type":"number","description":"amount / net sales of the connection, as a fraction. `0` when net sales are `0` for the window."},"previous_amount":{"nullable":true,"type":"number"}},"required":["object","connection","ad_platform","amount","pct_of_net_sales","previous_amount"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"currency":{"type":"string"}},"required":["object","data","has_more","currency"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/freshness":{"get":{"description":"How complete this P&L is right now: the last day each native source (`amazon_economics`, `amazon_vendor`, `amazon_ads`, `unit_costs`) actually has a row for, inside the requested window. Use it before reading `/v1/pnl/cascade` or `/v1/pnl/products` for a recent period, to tell a real gap from data that has simply not arrived yet - Data Kiosk economics lag 48-72h. No `currency`: nothing here is a monetary amount. On Free/Guru plans `unit_costs` never appears in `sources` - see `includes_product_cost`. A `connection` outside the ones this credential can read comes back as an empty `sources` list, not an error.","summary":"Last day with data per P&L source in the window","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_freshness"]},"includes_product_cost":{"type":"boolean","description":"Whether `unit_costs` can appear in `sources` at all. `false` on Free/Guru plans: the source is omitted from the list entirely, not reported with a `null` date."},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["amazon_economics","amazon_vendor","amazon_ads","unit_costs"],"description":"Native source of the line: `amazon_economics` (seller sales/fees from Data Kiosk), `amazon_vendor` (vendor sales), `amazon_ads` (advertising spend) or `unit_costs` (product cost)."},"last_date":{"nullable":true,"description":"Last day with data from this source in the window. `null` when the source has no rows at all in it - not necessarily a problem, e.g. a seller-only account never has `amazon_vendor`.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["source","last_date"],"additionalProperties":false}}},"required":["object","includes_product_cost","sources"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/products/{id}/costs":{"post":{"description":"Same two independent cost timelines as the product ficha and the CSV template: unit cost (COGS) and shipping cost, each with its own effective date. At least one of `price`/`shipping_cost` is required. Writing one does not touch the other - send both to update them together in one call. `404` when `id` does not exist, is not a catalog product (Amazon Seller or Vendor) or falls outside the connections this credential can read. `409` when a recalculation from an earlier cost change on the same connection is still running - retry once it finishes. Does not accept the CSV bulk-import template; this is the single-product write only.","summary":"Set a product's unit cost and/or shipping cost","tags":["product-costs"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"price":{"description":"New unit cost (COGS), in `currency`. Omit to leave the product's unit cost untouched - `0` sets it to zero, it is not the same as omitting the field.","type":"number","minimum":0},"shipping_cost":{"description":"New shipping cost, in `currency`. Omit to leave the product's shipping cost untouched - `0` sets it to zero, it is not the same as omitting the field.","type":"number","minimum":0},"currency":{"description":"ISO 4217 currency of `price` and `shipping_cost`. Defaults to the product's marketplace currency when omitted.","type":"string","pattern":"^[A-Z]{3}$"},"date":{"description":"Day the new cost(s) start applying from (YYYY-MM-DD). Defaults to today. A date in the past recalculates the margin of periods already closed in `/v1/pnl/*`; a date in the future is rejected with a 400.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["product_cost_write"]},"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"cogs":{"nullable":true,"type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"recalculation":{"type":"string","enum":["queued","not_needed","failed"],"description":"`queued` when `valid_from` is in the past and the recalculation of past periods was enqueued; `not_needed` for a current or absent date; `failed` when the enqueue itself could not be confirmed (the cost was still written - retry the request with the same `price`/`shipping_cost`/`date` and a new idempotency key to try the recalculation again)."}},"required":["unit_cost","currency","valid_from","recalculation"],"additionalProperties":false},"shipping":{"nullable":true,"type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"recalculation":{"type":"string","enum":["queued","not_needed","failed"],"description":"`queued` when `valid_from` is in the past and the recalculation of past periods was enqueued; `not_needed` for a current or absent date; `failed` when the enqueue itself could not be confirmed (the cost was still written - retry the request with the same `price`/`shipping_cost`/`date` and a new idempotency key to try the recalculation again)."}},"required":["unit_cost","currency","valid_from","recalculation"],"additionalProperties":false}},"required":["object","product","cogs","shipping"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns":{"get":{"summary":"List the authenticated account's advertising campaigns","tags":["campaigns"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the campaign name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"state","in":"query","schema":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"Created `PAUSED` unless you pass `state: \"ENABLED\"` explicitly: an enabled campaign starts spending as soon as Amazon accepts it. `dailyBudget` is checked against the marketplace minimum for the connection country and rejected with 400 below it. Requires the `campaigns:write` scope and an `Idempotency-Key` header. Sponsored Brands and Sponsored Display campaigns cannot be created here yet; they can be changed and archived like any other.","summary":"Create a Sponsored Products campaign, paused by default","tags":["campaigns"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string","minLength":1,"maxLength":128},"dailyBudget":{"type":"number","minimum":0,"exclusiveMinimum":true},"targetingType":{"type":"string","enum":["AUTO","MANUAL"]},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["connection","name","dailyBudget","targetingType"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/{id}":{"get":{"tags":["campaigns"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"Send only the fields you want to change; anything you omit is left as it is. At least one field is required. A campaign that does not exist, or belongs to another account, is a 404 - never a 403, which would confirm it exists. A campaign managed by the optimizer is refused, because its next run would overwrite you. If Amazon rejects the change the response is still 200 with `result: \"failed\"` and the reason, so you can tell \"Amazon said no\" from \"the call never happened\". Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Change the state, budget, name or portfolio of a campaign","tags":["campaigns"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"dailyBudget":{"type":"number","minimum":0,"exclusiveMinimum":true},"name":{"type":"string","minLength":1,"maxLength":128},"portfolioId":{"description":"Amazon id of the portfolio to move the campaign into (the `portfolioId` of the portfolios resource), or null to take it out of its portfolio. It must belong to the same advertising account as the campaign.","nullable":true,"type":"string","minLength":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"description":"Archiving is how Amazon removes an entity, and it CANNOT BE UNDONE: an archived campaign does not come back, and this is the only irreversible operation in this API. That is why it is its own verb instead of a `state` you could set by accident while changing a bid. Use `state: \"PAUSED\"` if you only want to stop it - that one is reversible. A campaign that does not exist, or belongs to another account, is a 404. One managed by the optimizer is refused. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Archive a campaign","tags":["campaigns"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/{id}/optimization-history":{"get":{"description":"Only changes that were APPLIED, and only for real: a dry-run simulation never appears here, under any parameter. Aggregated to a net per entity — `data` carries one row per target whose bid was moved, with the bid from before the first change against the bid after the last one, so a target raised then capped back down reports `direction: unchanged` with `change_count: 2`. That is the reading a flat decision list hides, and it is usually the answer to whether the optimization is doing anything. Proposals are excluded: the optimizer computes a bid the economic ceiling can then cut, and only what reached Amazon is reported. Non-bid changes (harvested keywords, negatives, placement adjustments, blocked or quarantined targets) do not share the table because they have no previous bid — they are counted in `other_changes`. Monetary amounts are decimal strings. The window is capped at 90 days, which is the retention of the underlying records.","summary":"Changes the workflow actually applied to this campaign","tags":["campaigns"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"start_date","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"limit","in":"query","description":"Page size, up to 500. Paginate with `offset`, not with a cursor: these rows are aggregated changes, not records with an id. Narrow the window with `start_date` / `end_date` instead of walking every page.","schema":{"default":100,"type":"integer","minimum":1,"maximum":500}},{"name":"offset","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"entity_type":{"type":"string","enum":["target"]},"adgroup":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"first_bid":{"nullable":true,"type":"string"},"last_bid":{"type":"string"},"net_change":{"nullable":true,"type":"string"},"direction":{"nullable":true,"type":"string","enum":["raised","lowered","unchanged"]},"change_count":{"type":"number"},"first_change_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"last_change_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"last_reason":{"nullable":true,"type":"string"},"last_scenario":{"nullable":true,"type":"string"}},"required":["id","entity_type","adgroup","first_bid","last_bid","net_change","direction","change_count","first_change_at","last_change_at","last_reason","last_scenario"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"other_changes":{"type":"array","items":{"type":"object","properties":{"entity_type":{"type":"string","enum":["target","searchTerm","campaign"]},"entity_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"change_type":{"type":"string"},"count":{"type":"number"},"last_change_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"last_reason":{"nullable":true,"type":"string"}},"required":["entity_type","entity_id","change_type","count","last_change_at","last_reason"],"additionalProperties":false}},"summary":{"type":"object","properties":{"targets_touched":{"type":"number"},"bid_changes":{"type":"number"},"raised":{"type":"number"},"lowered":{"type":"number"},"unchanged":{"type":"number"},"other_changes":{"type":"number"},"window":{"type":"object","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"}},"required":["start_date","end_date"],"additionalProperties":false}},"required":["targets_touched","bid_changes","raised","lowered","unchanged","other_changes","window"],"additionalProperties":false}},"required":["object","data","has_more","other_changes","summary"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/full":{"post":{"description":"One call for the whole structure, in order: campaign, ad group, targets, product ads. There is NO rollback on Amazon — if a later step fails the earlier entities stay created, and the response tells you how far it got in `stopped_at` plus what went wrong in `partial_errors`. Read that instead of retrying: a retry would create a second campaign. Everything is created paused unless you ask otherwise. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Create a campaign with its ad group, targets and product ads","tags":["campaigns"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string","minLength":1,"maxLength":128},"dailyBudget":{"type":"number","minimum":0,"exclusiveMinimum":true},"targetingType":{"type":"string","enum":["AUTO","MANUAL"]},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["connection","name","dailyBudget","targetingType"],"additionalProperties":false},"adGroup":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":255},"defaultBid":{"type":"number","minimum":0,"exclusiveMinimum":true},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]}},"required":["name","defaultBid"],"additionalProperties":false},"targets":{"maxItems":1000,"type":"array","items":{"type":"object","properties":{"targetType":{"type":"string","enum":["KEYWORD","PRODUCT","PRODUCT_CATEGORY","THEME","PRODUCT_AUDIENCE","AUDIENCE","CONTENT_CATEGORY","LOCATION"],"description":"Sponsored Products: KEYWORD, PRODUCT, PRODUCT_CATEGORY. Sponsored Brands: those plus THEME. Sponsored Display: all of them. The ad product is the one of the ad group."},"negative":{"default":false,"type":"boolean"},"keywordText":{"type":"string"},"matchType":{"type":"string","enum":["EXACT","PHRASE","BROAD"]},"asin":{"type":"string"},"sku":{"description":"Sponsored Display PRODUCT only: target a product by SKU instead of ASIN.","type":"string"},"productMatchType":{"description":"PRODUCT and PRODUCT_AUDIENCE. Sponsored Products: ASIN_SAME_AS or ASIN_EXPANDED_FROM. Sponsored Brands: PRODUCT_EXACT. Sponsored Display: PRODUCT_EXACT or PRODUCT_SIMILAR.","type":"string"},"category":{"type":"string"},"productBrand":{"description":"PRODUCT_CATEGORY refinement: brand id.","type":"string"},"productPriceGreaterThan":{"type":"number"},"productPriceLessThan":{"type":"number"},"productRatingGreaterThan":{"type":"number"},"productRatingLessThan":{"type":"number"},"productAgeRange":{"description":"Sponsored Display PRODUCT_CATEGORY refinement: age range id.","type":"string"},"productPrimeShippingEligible":{"description":"Sponsored Display PRODUCT_CATEGORY refinement.","type":"boolean"},"themeMatchType":{"description":"THEME. Sponsored Brands: KEYWORDS_RELATED_TO_YOUR_BRAND or KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES. Sponsored Display: INTERESTED_AUDIENCE.","type":"string","enum":["KEYWORDS_RELATED_TO_YOUR_BRAND","KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES","INTERESTED_AUDIENCE"]},"event":{"description":"Sponsored Display PRODUCT_AUDIENCE: shoppers who bought or viewed the ASIN.","type":"string","enum":["PURCHASE","VIEW"]},"lookback":{"description":"Sponsored Display PRODUCT_AUDIENCE, in days: 7, 14, 30, 60, 90, 180 or 365.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"audienceId":{"description":"Sponsored Display AUDIENCE: Amazon audience id.","type":"string"},"contentCategoryId":{"description":"Sponsored Display CONTENT_CATEGORY: Amazon content category id.","type":"string"},"locationId":{"description":"Sponsored Display LOCATION: Amazon location id.","type":"string"},"bid":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["targetType"],"additionalProperties":false}},"productAds":{"maxItems":1000,"type":"array","items":{"type":"object","properties":{"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]}},"required":["product"],"additionalProperties":false}}},"required":["campaign","adGroup"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adgroup":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"targets_created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"product_ads_created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"stopped_at":{"type":"string","enum":["campaign","adgroup","targets","productAds","done"]},"partial_errors":{"type":"array","items":{"type":"string"}}},"required":["success","campaign","adgroup","targets_created","product_ads_created","stopped_at","partial_errors"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/{id}/optimization-config":{"patch":{"description":"Sets what the optimizer chases for this campaign: target ACOS or ROAS, bid floor and ceiling, monthly budget, harvesting overrides, and which workflows may touch it. None of this reaches Amazon - it is the configuration Epinium optimizes against, so no `Idempotency-Key` is required. Read the current values with `GET /v1/campaigns/:id?expand[]=optimizationConfig`. **What puts a campaign under the optimizer is `linkedWorkflowDefinitionIds`: a workflow listed there processes it every night and moves real bids on Amazon** - confirm it with the person first, exactly as you would turning a workflow on. A workflow that selects campaigns on its own can also pick it up, and `workflowsOptOut: true` is what declines that; the only setting that always keeps a workflow away is `excludedWorkflowDefinitionIds`, which wins over the other two. `aiEnabled` is NOT that switch: it records the account holder consent, travels to Amazon as the `epinium:ai_enabled` tag and makes the campaign eligible as a cross-harvest peer, so `aiEnabled: false` does NOT take a campaign out of the optimizer - remove it from `linkedWorkflowDefinitionIds` (plus `workflowsOptOut: true` if the workflow selects campaigns on its own) or add the workflow to `excludedWorkflowDefinitionIds` instead. `optimizeDate` and `optimizingSince` are read-only, stamped by the optimizer itself, and sending either is a 400. Requires `campaigns:write`.","summary":"Update Epinium's own optimization settings for a campaign","tags":["campaigns"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"aiEnabled":{"description":"The account holder's consent flag. It is exported to Amazon as the `epinium:ai_enabled` tag and decides whether the campaign can act as a cross-harvest peer. It does NOT put the campaign under the optimizer and does NOT take it out: that is `linkedWorkflowDefinitionIds` and `excludedWorkflowDefinitionIds`.","type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"nullable":true,"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}}},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}}},"budget":{"description":"The optimizer's own spend targets. `dailyBudget` here is NOT the campaign's Amazon daily budget: it is the pacing anchor the optimizer spends against, and nothing in this block travels to Amazon. The real Amazon budget is the `budget` field of the campaign resource, changed with `PATCH /v1/campaigns/:id`. Two different things with the same name.","nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}}},"harvesting":{"description":"Per-campaign harvesting overrides. `crossCampaign` is REPLACED whole, not merged: sending `{enabled: true}` on its own wipes `harvestGroupKey` and `role`, the two fields cross-harvest uses to find this campaign peers, so resend them alongside it. The other keys of this block do merge field by field.","nullable":true,"type":"object","properties":{"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"nullable":true,"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}}},"discoveryLevel":{"nullable":true,"type":"string","enum":["bids-only","harvesting","discovery"]},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}}},"warmingModeUntil":{"description":"ISO-8601 timestamp until which the campaign stays in warming mode, or `null` to clear it. A UTC `Z` timestamp or one with a numeric offset both work; anything that is not a valid ISO-8601 datetime is rejected with a 400.","nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"linkedWorkflowDefinitionIds":{"description":"Force-include: every workflow listed here processes this campaign each night, skipping its own selection filter. **This is what puts a campaign under the optimizer, which moves real bids on Amazon** - confirm it with the person before adding one. Replaces the whole list.","type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"description":"Force-exclude, and it wins over the other two: a workflow listed here never touches this campaign, whatever else is set. This is how you reliably take a campaign out of the optimizer. Replaces the whole list.","type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"description":"Declines automatic selection: with `true`, only the workflows in `linkedWorkflowDefinitionIds` process this campaign. It only bites on workflows that select campaigns by themselves - against a workflow that has this campaign linked it changes nothing.","type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"paths":{"type":"array","items":{"type":"string"}},"reason":{"nullable":true,"type":"string","enum":["not_found","unowned_workflow","validation"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","paths","reason","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/optimization-config/batch":{"post":{"description":"NOT all-or-nothing: `data` carries one row per campaign you sent, in the order you sent them. A row that fails validation comes back `failed` with the reason and the others still apply, because each campaign is validated against its OWN stored state - a bid ceiling that is mandatory for one objective may be absent in another campaign. **The warning about `linkedWorkflowDefinitionIds` applies to every row**: enrolling a batch puts all of those campaigns under a workflow that moves real bids on Amazon every night, so confirm it with the person before doing it wholesale. `aiEnabled` is consent and an Amazon tag, not the enrolment switch, in the batch exactly as in the single. Requires `campaigns:write`.","summary":"Same update for up to 1000 campaigns, one patch per row","tags":["campaigns"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"aiEnabled":{"description":"The account holder's consent flag. It is exported to Amazon as the `epinium:ai_enabled` tag and decides whether the campaign can act as a cross-harvest peer. It does NOT put the campaign under the optimizer and does NOT take it out: that is `linkedWorkflowDefinitionIds` and `excludedWorkflowDefinitionIds`.","type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"nullable":true,"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}}},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}}},"budget":{"description":"The optimizer's own spend targets. `dailyBudget` here is NOT the campaign's Amazon daily budget: it is the pacing anchor the optimizer spends against, and nothing in this block travels to Amazon. The real Amazon budget is the `budget` field of the campaign resource, changed with `PATCH /v1/campaigns/:id`. Two different things with the same name.","nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}}},"harvesting":{"description":"Per-campaign harvesting overrides. `crossCampaign` is REPLACED whole, not merged: sending `{enabled: true}` on its own wipes `harvestGroupKey` and `role`, the two fields cross-harvest uses to find this campaign peers, so resend them alongside it. The other keys of this block do merge field by field.","nullable":true,"type":"object","properties":{"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"nullable":true,"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}}},"discoveryLevel":{"nullable":true,"type":"string","enum":["bids-only","harvesting","discovery"]},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}}},"warmingModeUntil":{"description":"ISO-8601 timestamp until which the campaign stays in warming mode, or `null` to clear it. A UTC `Z` timestamp or one with a numeric offset both work; anything that is not a valid ISO-8601 datetime is rejected with a 400.","nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"linkedWorkflowDefinitionIds":{"description":"Force-include: every workflow listed here processes this campaign each night, skipping its own selection filter. **This is what puts a campaign under the optimizer, which moves real bids on Amazon** - confirm it with the person before adding one. Replaces the whole list.","type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"description":"Force-exclude, and it wins over the other two: a workflow listed here never touches this campaign, whatever else is set. This is how you reliably take a campaign out of the optimizer. Replaces the whole list.","type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"description":"Declines automatic selection: with `true`, only the workflows in `linkedWorkflowDefinitionIds` process this campaign. It only bites on workflows that select campaigns by themselves - against a workflow that has this campaign linked it changes nothing.","type":"boolean"},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"required":["id"],"additionalProperties":false}}},"required":["changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"paths":{"type":"array","items":{"type":"string"}},"reason":{"nullable":true,"type":"string","enum":["not_found","unowned_workflow","validation"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","paths","reason","error"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/batch":{"post":{"description":"Same fields as the single update, up to 1000 campaigns per call - the cap is the per-request limit Amazon itself declares. NOT all-or-nothing: `data` carries one row per campaign you sent, in the order you sent them, and `applied` is what actually reached Amazon. Only `applied` rows are billed. A campaign is `applied` only when EVERY field you asked for went through: if the state changes and the budget is rejected, that campaign is `failed` with the reason, because reporting it as applied is how an agent concludes the budget moved when it did not. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Change state, budget, name or portfolio on up to 1000 campaigns","tags":["campaigns"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"dailyBudget":{"type":"number","minimum":0,"exclusiveMinimum":true},"name":{"type":"string","minLength":1,"maxLength":128},"portfolioId":{"description":"Amazon id of the portfolio to move the campaign into (the `portfolioId` of the portfolios resource), or null to take it out of its portfolio. It must belong to the same advertising account as the campaign.","nullable":true,"type":"string","minLength":1},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"required":["id"],"additionalProperties":false}}},"required":["changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/portfolios":{"get":{"summary":"List the authenticated account's portfolios and their budget caps","tags":["portfolios"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"search","in":"query","description":"Case-insensitive substring match over the portfolio name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"state","in":"query","schema":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"portfolioId":{"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"budget":{"nullable":true,"type":"object","properties":{"policy":{"nullable":true,"type":"string","enum":["MONTHLY_RECURRING","DATE_RANGE","NO_CAP","OTHER"]},"amount":{"nullable":true,"type":"number"},"currencyCode":{"nullable":true,"type":"string"},"startDate":{"nullable":true,"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"nullable":true,"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["policy","amount","currencyCode","startDate","endDate"],"additionalProperties":false},"inBudget":{"nullable":true,"type":"boolean"},"servingStatus":{"nullable":true,"type":"string"},"statusReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","portfolioId","name","state","connection","country","budget","inBudget","servingStatus","statusReasons","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"Creates a portfolio in the Amazon Ads account of `connection`. `budget` caps what ALL the campaigns in the portfolio can spend together: `MONTHLY_RECURRING` resets every month, `DATE_RANGE` applies between `startDate` and `endDate`, `NO_CAP` removes the cap. The currency is the marketplace one; you do not send it. If Amazon rejects the portfolio the response is still 201 with `result: \"failed\"`, the reason in `error` and `id: null`. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Create a portfolio, optionally with a budget cap","tags":["portfolios"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string","minLength":1,"maxLength":255},"state":{"default":"ENABLED","type":"string","enum":["ENABLED","PAUSED"]},"budget":{"type":"object","properties":{"policy":{"type":"string","enum":["MONTHLY_RECURRING","DATE_RANGE","NO_CAP"]},"amount":{"description":"Cap amount in the marketplace currency. Required for MONTHLY_RECURRING and DATE_RANGE; omit it for NO_CAP.","type":"number","minimum":0,"exclusiveMinimum":true},"startDate":{"description":"YYYY-MM-DD. Required for DATE_RANGE.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"description":"YYYY-MM-DD. Required for DATE_RANGE.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["policy"],"additionalProperties":false}},"required":["connection","name"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/portfolios/{id}":{"get":{"tags":["portfolios"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"portfolioId":{"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"budget":{"nullable":true,"type":"object","properties":{"policy":{"nullable":true,"type":"string","enum":["MONTHLY_RECURRING","DATE_RANGE","NO_CAP","OTHER"]},"amount":{"nullable":true,"type":"number"},"currencyCode":{"nullable":true,"type":"string"},"startDate":{"nullable":true,"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"nullable":true,"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["policy","amount","currencyCode","startDate","endDate"],"additionalProperties":false},"inBudget":{"nullable":true,"type":"boolean"},"servingStatus":{"nullable":true,"type":"string"},"statusReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","portfolioId","name","state","connection","country","budget","inBudget","servingStatus","statusReasons","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"Send only what you want to change; at least one field is required. `budget` is replaced whole: send the full cap you want, not just the amount. A portfolio that does not exist, or belongs to another account, is a 404. If Amazon rejects the change the response is still 200 with `result: \"failed\"` and the reason, and nothing is changed on our side. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Change the name, state or budget cap of a portfolio","tags":["portfolios"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"state":{"type":"string","enum":["ENABLED","PAUSED"]},"budget":{"type":"object","properties":{"policy":{"type":"string","enum":["MONTHLY_RECURRING","DATE_RANGE","NO_CAP"]},"amount":{"description":"Cap amount in the marketplace currency. Required for MONTHLY_RECURRING and DATE_RANGE; omit it for NO_CAP.","type":"number","minimum":0,"exclusiveMinimum":true},"startDate":{"description":"YYYY-MM-DD. Required for DATE_RANGE.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"description":"YYYY-MM-DD. Required for DATE_RANGE.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["policy"],"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaign-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window. Unlike the rest of the API, this resource paginates with `limit`/`offset` (an aggregated row has no id to use as a cursor) and `has_more` tells whether another page follows. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero. With `group_by`, rows are aggregated across entities (see the parameter) and `total_count` counts groups, or group-periods when `granularity` is not `total`.","summary":"Advertising performance per campaign, from the account's report history","tags":["campaign-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`), and the credits scale with the groups returned, not with the number of products. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country"]}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_product","in":"query","schema":{"type":"string","enum":["SP","SB","SD"]}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["cost","sales","impressions","clicks","orders","units","acos","roas","ctr","cpc","conversion_rate"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["campaign_metrics"]},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_product":{"type":"string","enum":["SP","SB","SD"]},"currency":{"type":"string"},"date":{"type":"string"},"impressions":{"type":"number"},"clicks":{"type":"number"},"cost":{"type":"string"},"sales":{"type":"string"},"orders":{"type":"number"},"units":{"type":"number"},"ctr":{"nullable":true,"type":"number"},"cpc":{"nullable":true,"type":"string"},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"type":"number"},"top_of_search_is":{"nullable":true,"type":"number"},"new_to_brand_sales":{"nullable":true,"type":"string"},"new_to_brand_purchases":{"nullable":true,"type":"number"},"detail_page_views":{"nullable":true,"type":"number"},"viewable_impressions":{"nullable":true,"type":"number"}},"required":["object","campaign","connection","country","ad_product","currency","impressions","clicks","cost","sales","orders","units","ctr","cpc","acos","roas","conversion_rate","top_of_search_is","new_to_brand_sales","new_to_brand_purchases","detail_page_views","viewable_impressions"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/adgroups":{"get":{"summary":"List the authenticated account's ad groups","tags":["adgroups"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the ad group name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"state","in":"query","schema":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"Created `PAUSED` unless you pass `state: \"ENABLED\"`. `defaultBid` is clamped to the marketplace bid limits for the campaign country, so a bid outside them is adjusted rather than rejected. The campaign must already be published on Amazon; one that belongs to another account is a 404, never a 403. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Create an ad group inside a Sponsored Products campaign","tags":["adgroups"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string","minLength":3,"maxLength":255},"defaultBid":{"type":"number","minimum":0,"exclusiveMinimum":true},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]},"targetType":{"type":"string","enum":["auto","keyword","product"]}},"required":["campaign","name","defaultBid"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/adgroups/{id}":{"get":{"tags":["adgroups"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"Send only the fields you want to change; anything you omit is left as it is. At least one field is required. `defaultBid` is checked against the marketplace bid limits before it is sent, so an out-of-range bid comes back with the limits instead of a generic rejection from Amazon. An ad group that does not exist, or belongs to another account, is a 404 - never a 403, which would confirm it exists. One managed by the optimizer is refused, because its next run would overwrite you. If Amazon rejects the change the response is still 200 with `result: \"failed\"` and the reason. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Change the state, default bid or name of an ad group","tags":["adgroups"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"defaultBid":{"type":"number","minimum":0,"exclusiveMinimum":true},"name":{"type":"string","minLength":3,"maxLength":255}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"description":"Archiving is how Amazon removes an entity, and it CANNOT BE UNDONE: an archived ad group does not come back, and this is the only irreversible operation in this API. That is why it is its own verb instead of a `state` you could set by accident while changing a bid. Use `state: \"PAUSED\"` if you only want to stop it - that one is reversible. An ad group that does not exist, or belongs to another account, is a 404. One managed by the optimizer is refused. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Archive a ad group","tags":["adgroups"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/adgroups/batch":{"post":{"description":"Same fields as the single update, up to 1000 ad groups per call - the cap is the per-request limit Amazon itself declares. NOT all-or-nothing: `data` carries one row per ad group you sent, in the order you sent them, and `applied` is what actually reached Amazon. Only `applied` rows are billed. An ad group is `applied` only when EVERY field you asked for went through. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Change state, default bid or name on up to 1000 ad groups","tags":["adgroups"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"defaultBid":{"type":"number","minimum":0,"exclusiveMinimum":true},"name":{"type":"string","minLength":3,"maxLength":255},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"required":["id"],"additionalProperties":false}}},"required":["changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/adgroup-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window. Like the rest of the metrics resources it paginates with `limit`/`offset` (an aggregated row has no id to use as a cursor) and `has_more` tells whether another page follows. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero. With `group_by`, rows are aggregated across entities (see the parameter) and `total_count` counts groups, or group-periods when `granularity` is not `total`.","summary":"Advertising performance per ad group, from the account's report history","tags":["adgroup-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`), and the credits scale with the groups returned, not with the number of products. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country"]}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_group","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_product","in":"query","schema":{"type":"string","enum":["SP","SB","SD"]}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["cost","sales","impressions","clicks","orders","units","acos","roas","ctr","cpc","conversion_rate"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["adgroup_metrics"]},"ad_group":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_product":{"type":"string","enum":["SP","SB","SD"]},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"currency":{"type":"string"},"date":{"type":"string"},"impressions":{"type":"number"},"clicks":{"type":"number"},"cost":{"type":"string"},"sales":{"type":"string"},"orders":{"type":"number"},"units":{"type":"number"},"ctr":{"nullable":true,"type":"number"},"cpc":{"nullable":true,"type":"string"},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"type":"number"},"new_to_brand_sales":{"nullable":true,"type":"string"},"new_to_brand_purchases":{"nullable":true,"type":"number"},"detail_page_views":{"nullable":true,"type":"number"},"viewable_impressions":{"nullable":true,"type":"number"}},"required":["object","ad_group","campaign","ad_product","connection","country","currency","impressions","clicks","cost","sales","orders","units","ctr","cpc","acos","roas","conversion_rate","new_to_brand_sales","new_to_brand_purchases","detail_page_views","viewable_impressions"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/targets":{"get":{"summary":"List the authenticated account's advertising targets","tags":["targets"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the target's expression (keyword, ASIN or category, chosen by `targetType`) and its `matchType`; with `targetType` set, only that type's field is searched. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"adGroup","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"state","in":"query","schema":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]}},{"name":"targetType","in":"query","schema":{"type":"string","enum":["AUTO","KEYWORD","PRODUCT_CATEGORY","PRODUCT","PRODUCT_CATEGORY_AUDIENCE","PRODUCT_AUDIENCE","AUDIENCE","THEME","CONTENT_CATEGORY","LOCATION"]}},{"name":"negative","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"targetId":{"nullable":true,"type":"string"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"negative":{"type":"boolean"},"bid":{"nullable":true,"type":"number"},"targetType":{"type":"string","enum":["AUTO","KEYWORD","PRODUCT_CATEGORY","PRODUCT","PRODUCT_CATEGORY_AUDIENCE","PRODUCT_AUDIENCE","AUDIENCE","THEME","CONTENT_CATEGORY","LOCATION"]},"targetLevel":{"nullable":true,"type":"string","enum":["CAMPAIGN","AD_GROUP"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","targetId","connection","country","campaign","adGroup","state","negative","bid","targetType","targetLevel","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"Creates up to 1000 targets in one call — the cap is Amazon's own per-request limit. NOT all-or-nothing: the response counts what went in and lists every rejection in `failure_details` with its reason, so a partial result is actionable instead of a retry that duplicates what already worked. Amazon rules are enforced before sending (negative keyword length and word count, category id coercion) and the ad group capacity is checked against the Amazon limits. The response returns COUNTS, not ids: list the ad group targets to get them. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Create keyword, product or category targets in an ad group","tags":["targets"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"adgroup":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"targets":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"targetType":{"type":"string","enum":["KEYWORD","PRODUCT","PRODUCT_CATEGORY","THEME","PRODUCT_AUDIENCE","AUDIENCE","CONTENT_CATEGORY","LOCATION"],"description":"Sponsored Products: KEYWORD, PRODUCT, PRODUCT_CATEGORY. Sponsored Brands: those plus THEME. Sponsored Display: all of them. The ad product is the one of the ad group."},"negative":{"default":false,"type":"boolean"},"keywordText":{"type":"string"},"matchType":{"type":"string","enum":["EXACT","PHRASE","BROAD"]},"asin":{"type":"string"},"sku":{"description":"Sponsored Display PRODUCT only: target a product by SKU instead of ASIN.","type":"string"},"productMatchType":{"description":"PRODUCT and PRODUCT_AUDIENCE. Sponsored Products: ASIN_SAME_AS or ASIN_EXPANDED_FROM. Sponsored Brands: PRODUCT_EXACT. Sponsored Display: PRODUCT_EXACT or PRODUCT_SIMILAR.","type":"string"},"category":{"type":"string"},"productBrand":{"description":"PRODUCT_CATEGORY refinement: brand id.","type":"string"},"productPriceGreaterThan":{"type":"number"},"productPriceLessThan":{"type":"number"},"productRatingGreaterThan":{"type":"number"},"productRatingLessThan":{"type":"number"},"productAgeRange":{"description":"Sponsored Display PRODUCT_CATEGORY refinement: age range id.","type":"string"},"productPrimeShippingEligible":{"description":"Sponsored Display PRODUCT_CATEGORY refinement.","type":"boolean"},"themeMatchType":{"description":"THEME. Sponsored Brands: KEYWORDS_RELATED_TO_YOUR_BRAND or KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES. Sponsored Display: INTERESTED_AUDIENCE.","type":"string","enum":["KEYWORDS_RELATED_TO_YOUR_BRAND","KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES","INTERESTED_AUDIENCE"]},"event":{"description":"Sponsored Display PRODUCT_AUDIENCE: shoppers who bought or viewed the ASIN.","type":"string","enum":["PURCHASE","VIEW"]},"lookback":{"description":"Sponsored Display PRODUCT_AUDIENCE, in days: 7, 14, 30, 60, 90, 180 or 365.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"audienceId":{"description":"Sponsored Display AUDIENCE: Amazon audience id.","type":"string"},"contentCategoryId":{"description":"Sponsored Display CONTENT_CATEGORY: Amazon content category id.","type":"string"},"locationId":{"description":"Sponsored Display LOCATION: Amazon location id.","type":"string"},"bid":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["targetType"],"additionalProperties":false}}},"required":["adgroup","targets"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failure_details":{"type":"array","items":{"type":"object","properties":{"reference":{"nullable":true,"type":"string"},"error":{"type":"string"}},"required":["reference","error"],"additionalProperties":false}}},"required":["created","failed","failure_details"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/targets/{id}":{"get":{"tags":["targets"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"targetId":{"nullable":true,"type":"string"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"negative":{"type":"boolean"},"bid":{"nullable":true,"type":"number"},"targetType":{"type":"string","enum":["AUTO","KEYWORD","PRODUCT_CATEGORY","PRODUCT","PRODUCT_CATEGORY_AUDIENCE","PRODUCT_AUDIENCE","AUDIENCE","THEME","CONTENT_CATEGORY","LOCATION"]},"targetLevel":{"nullable":true,"type":"string","enum":["CAMPAIGN","AD_GROUP"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","targetId","connection","country","campaign","adGroup","state","negative","bid","targetType","targetLevel","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"Send only the fields you want to change; anything you omit is left as it is. At least one field is required. Only state and bid: what defines a target - its keyword, its ASIN, its match type - is not editable on Amazon, so to change that you create another and archive this one. A negative target has no bid and asking for one is refused. `bid` is checked against the marketplace limits before it is sent. A target that does not exist, or belongs to another account, is a 404 - never a 403. If Amazon rejects the change the response is still 200 with `result: \"failed\"`. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Change the state or bid of a target","tags":["targets"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"bid":{"type":"number","minimum":0,"exclusiveMinimum":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"description":"Archiving is how Amazon removes an entity, and it CANNOT BE UNDONE: an archived target does not come back, and this is the only irreversible operation in this API. That is why it is its own verb instead of a `state` you could set by accident while changing a bid. Use `state: \"PAUSED\"` if you only want to stop it - that one is reversible. A target that does not exist, or belongs to another account, is a 404. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Archive a target","tags":["targets"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/targets/batch":{"post":{"description":"This is the bid sweep: up to 1000 targets in ONE call, each with its own bid - the cap is the per-request limit Amazon itself declares. Prefer it over calling the single update in a loop. NOT all-or-nothing: `data` carries one row per target you sent, in the order you sent them, and `applied` is what actually reached Amazon. Only `applied` rows are billed, so a partial result costs you only what worked. A target is `applied` only when EVERY field you asked for went through. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Change state or bid on up to 1000 targets","tags":["targets"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"bid":{"type":"number","minimum":0,"exclusiveMinimum":true},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"required":["id"],"additionalProperties":false}}},"required":["changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/target-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window, with the target type and keyword resolved from the catalog. This is one of the two heaviest resources, so its window is capped shorter: 93 days for `granularity=total` and 31 for `daily`. Paginates with `limit`/`offset` and `has_more` tells whether another page follows. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero. With `group_by`, rows are aggregated across entities (see the parameter) and `total_count` counts groups, or group-periods when `granularity` is not `total`.","summary":"Advertising performance per target, from the account's report history","tags":["target-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`), and the credits scale with the groups returned, not with the number of products. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country"]}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_group","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"target","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_product","in":"query","schema":{"type":"string","enum":["SP","SB","SD"]}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["cost","sales","impressions","clicks","orders","units","acos","roas","ctr","cpc","conversion_rate"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["target_metrics"]},"target":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"target_type":{"nullable":true,"type":"string"},"match_type":{"nullable":true,"type":"string"},"target_expression":{"nullable":true,"type":"string"},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_group":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_product":{"type":"string","enum":["SP","SB","SD"]},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"currency":{"type":"string"},"date":{"type":"string"},"impressions":{"type":"number"},"clicks":{"type":"number"},"cost":{"type":"string"},"sales":{"type":"string"},"orders":{"type":"number"},"units":{"type":"number"},"ctr":{"nullable":true,"type":"number"},"cpc":{"nullable":true,"type":"string"},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"type":"number"},"new_to_brand_sales":{"nullable":true,"type":"string"},"new_to_brand_purchases":{"nullable":true,"type":"number"},"detail_page_views":{"nullable":true,"type":"number"},"viewable_impressions":{"nullable":true,"type":"number"}},"required":["object","target","target_type","match_type","target_expression","campaign","ad_group","ad_product","connection","country","currency","impressions","clicks","cost","sales","orders","units","ctr","cpc","acos","roas","conversion_rate","new_to_brand_sales","new_to_brand_purchases","detail_page_views","viewable_impressions"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-ads":{"get":{"summary":"List the authenticated account's advertising product ads","tags":["product-ads"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the advertised ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"adGroup","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"product","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adId":{"nullable":true,"type":"string"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"product":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","createdAt","updatedAt"],"additionalProperties":false}]},"asin":{"nullable":true,"type":"string"},"sku":{"nullable":true,"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"adType":{"type":"string","enum":["PRODUCT_AD","IMAGE","VIDEO","PRODUCT_COLLECTION","STORE_SPOTLIGHT","BRAND_VIDEO"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","adId","connection","country","campaign","adGroup","product","asin","sku","state","adType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"Each entry links one catalog product to the ad group. Products are resolved against YOUR catalog: one that is not there, or that lacks the identifier the account needs (ASIN for Vendor, SKU for Seller), is reported in `failure_details` with that reason instead of failing the whole call. Created `PAUSED` unless asked otherwise. The response returns COUNTS, not ids: list the ad group product ads to get them. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Advertise catalog products in an ad group","tags":["product-ads"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"adgroup":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"productAds":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]}},"required":["product"],"additionalProperties":false}}},"required":["adgroup","productAds"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failure_details":{"type":"array","items":{"type":"object","properties":{"reference":{"nullable":true,"type":"string"},"error":{"type":"string"}},"required":["reference","error"],"additionalProperties":false}}},"required":["created","failed","failure_details"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-ads/{id}":{"get":{"tags":["product-ads"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adId":{"nullable":true,"type":"string"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"product":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","createdAt","updatedAt"],"additionalProperties":false}]},"asin":{"nullable":true,"type":"string"},"sku":{"nullable":true,"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"adType":{"type":"string","enum":["PRODUCT_AD","IMAGE","VIDEO","PRODUCT_COLLECTION","STORE_SPOTLIGHT","BRAND_VIDEO"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","adId","connection","country","campaign","adGroup","product","asin","sku","state","adType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"State is the only writable field: a product ad links one catalog product to an ad group and has no bid or name of its own. A product ad that does not exist, or belongs to another account, is a 404 - never a 403. If Amazon rejects the change the response is still 200 with `result: \"failed\"` and the reason. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Enable or pause a product ad","tags":["product-ads"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"description":"Archiving is how Amazon removes an entity, and it CANNOT BE UNDONE: an archived product ad does not come back, and this is the only irreversible operation in this API. That is why it is its own verb instead of a `state` you could set by accident while changing a bid. Use `state: \"PAUSED\"` if you only want to stop it - that one is reversible. A product ad that does not exist, or belongs to another account, is a 404. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Archive a product ad","tags":["product-ads"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-ads/batch":{"post":{"description":"Up to 1000 product ads per call - the cap is the per-request limit Amazon itself declares. NOT all-or-nothing: `data` carries one row per product ad you sent, in the order you sent them, and `applied` is what actually reached Amazon. Only `applied` rows are billed. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Enable or pause up to 1000 product ads","tags":["product-ads"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"required":["id"],"additionalProperties":false}}},"required":["changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-ad-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window. Only Sponsored Products and Sponsored Display have product ads; Sponsored Brands does not, so `ad_product` accepts SP and SD only. Paginates with `limit`/`offset` and `has_more` tells whether another page follows. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero. With `group_by`, rows are aggregated across entities (see the parameter) and `total_count` counts groups, or group-periods when `granularity` is not `total`.","summary":"Advertising performance per product ad, from the account's report history","tags":["product-ad-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`), and the credits scale with the groups returned, not with the number of products. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter. `cluster` gives one row per product cluster (the `clusters` resource), with its id in `cluster` and its name in `cluster_name`. A product in several clusters counts in full in each of them, so the cluster rows do NOT add up to the account total, and products in no cluster are left out. It combines with `connection` and `country`, and with the `cluster` filter to choose which clusters come back.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country","cluster"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country","cluster"]}}]}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_group","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"product_ad","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`.","schema":{"type":"string","pattern":"^[A-Z0-9]{10}$"}},{"name":"ad_product","in":"query","schema":{"type":"string","enum":["SP","SD"]}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["cost","sales","impressions","clicks","orders","units","acos","roas","ctr","cpc","conversion_rate"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["product_ad_metrics"]},"product_ad":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"product":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"nullable":true,"type":"string"},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_group":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"cluster":{"nullable":true,"description":"Product cluster of the row, only with `group_by=cluster`; `null` otherwise.","type":"string","pattern":"^[a-f0-9]{24}$"},"cluster_name":{"nullable":true,"description":"Name of the product cluster, only with `group_by=cluster`; `null` otherwise.","type":"string"},"ad_product":{"type":"string","enum":["SP","SD"]},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"currency":{"type":"string"},"date":{"type":"string"},"impressions":{"type":"number"},"clicks":{"type":"number"},"cost":{"type":"string"},"sales":{"type":"string"},"orders":{"type":"number"},"units":{"type":"number"},"ctr":{"nullable":true,"type":"number"},"cpc":{"nullable":true,"type":"string"},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"type":"number"},"new_to_brand_sales":{"nullable":true,"type":"string"},"new_to_brand_purchases":{"nullable":true,"type":"number"},"detail_page_views":{"nullable":true,"type":"number"},"viewable_impressions":{"nullable":true,"type":"number"}},"required":["object","product_ad","product","asin","campaign","ad_group","cluster","cluster_name","ad_product","connection","country","currency","impressions","clicks","cost","sales","orders","units","ctr","cpc","acos","roas","conversion_rate","new_to_brand_sales","new_to_brand_purchases","detail_page_views","viewable_impressions"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/search-terms":{"get":{"summary":"List the authenticated account's advertising search terms","tags":["search-terms"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the shopper search term text. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"adGroup","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"searchTerm","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"searchTerm":{"type":"string"},"searchTermTargetType":{"nullable":true,"type":"string","enum":["AUTO","KEYWORD","PRODUCT_CATEGORY","PRODUCT","PRODUCT_CATEGORY_AUDIENCE","PRODUCT_AUDIENCE","AUDIENCE","THEME","CONTENT_CATEGORY","LOCATION"]},"targetSourceMatchType":{"type":"string"},"lastReportDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","connection","country","campaign","adGroup","searchTerm","searchTermTargetType","targetSourceMatchType","lastReportDate","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/search-terms/{id}":{"get":{"tags":["search-terms"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"},"crossCampaign":{"nullable":true,"type":"object","properties":{"enabled":{"type":"boolean"},"harvestGroupKey":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string","enum":["validation","performance"]}},"required":["enabled","harvestGroupKey","role"],"additionalProperties":false}},"required":["discoveryLevel","competitorAsinTargeting","crossCampaign"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"searchTerm":{"type":"string"},"searchTermTargetType":{"nullable":true,"type":"string","enum":["AUTO","KEYWORD","PRODUCT_CATEGORY","PRODUCT","PRODUCT_CATEGORY_AUDIENCE","PRODUCT_AUDIENCE","AUDIENCE","THEME","CONTENT_CATEGORY","LOCATION"]},"targetSourceMatchType":{"type":"string"},"lastReportDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","adProduct","connection","country","campaign","adGroup","searchTerm","searchTermTargetType","targetSourceMatchType","lastReportDate","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/skills":{"get":{"summary":"List available marketing skills","tags":["skills"],"parameters":[{"name":"search","in":"query","description":"Case-insensitive substring match over the skill name and description. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"integration","in":"query","schema":{"type":"string"}},{"name":"division","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"division":{"type":"string"},"integrations":{"type":"array","items":{"type":"string"}},"blocks":{"type":"array","items":{"type":"string","enum":["advisor","assisted","autonomous"]}},"references":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","division","integrations","blocks","references"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/skills/{id}":{"get":{"summary":"Get one skill, or one of its reference documents","tags":["skills"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"reference","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"division":{"type":"string"},"integrations":{"type":"array","items":{"type":"string"}},"blocks":{"type":"array","items":{"type":"string","enum":["advisor","assisted","autonomous"]}},"references":{"type":"array","items":{"type":"string"}},"content":{"type":"string"},"reference":{"type":"string"}},"required":["id","name","description","division","integrations","blocks","references","content"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/search-term-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window, with the shopper query resolved from the catalog into `query`. Answers \"which searches do I spend most on?\": use `order_by=cost` with `limit` instead of paging. This is the heaviest resource in the API, so its window is capped shorter: 93 days for `granularity=total` and 31 for `daily`. Rows are grouped per search term AND target, because the same text can be matched by different targets. Only Sponsored Products and Sponsored Brands produce search terms, so `ad_product` accepts SP and SB only. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero. With `group_by`, rows are aggregated across entities (see the parameter) and `total_count` counts groups, or group-periods when `granularity` is not `total`.","summary":"Advertising performance per shopper search term, from the account's report history","tags":["search-term-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`), and the credits scale with the groups returned, not with the number of products. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country"]}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_group","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"target","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"search_term","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_product","in":"query","schema":{"type":"string","enum":["SP","SB"]}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["cost","sales","impressions","clicks","orders","units","acos","roas","ctr","cpc","conversion_rate"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["search_term_metrics"]},"search_term":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"query":{"nullable":true,"type":"string"},"target":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_group":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_product":{"type":"string","enum":["SP","SB"]},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"currency":{"type":"string"},"date":{"type":"string"},"impressions":{"type":"number"},"clicks":{"type":"number"},"cost":{"type":"string"},"sales":{"type":"string"},"orders":{"type":"number"},"units":{"type":"number"},"ctr":{"nullable":true,"type":"number"},"cpc":{"nullable":true,"type":"string"},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"type":"number"}},"required":["object","search_term","query","target","campaign","ad_group","ad_product","connection","country","currency","impressions","clicks","cost","sales","orders","units","ctr","cpc","acos","roas","conversion_rate"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/clusters":{"get":{"summary":"List the authenticated account's keyword clusters","tags":["clusters"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the cluster name and its positive and negative keywords. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"notes":{"nullable":true,"type":"string"},"positiveKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"negativeKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"protected":{"type":"boolean"},"productCount":{"type":"number"},"products":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","createdAt","updatedAt"],"additionalProperties":false}}]},"prompts":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","notes","positiveKeywords","negativeKeywords","protected","productCount","prompts","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Create a keyword cluster","tags":["clusters"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Name shown in the Epinium clusters table."},"positiveKeywords":{"description":"Keywords the products should rank or advertise for, up to 100.","maxItems":100,"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string","minLength":1,"maxLength":80,"pattern":"^(?![-.])(?!.*\\s-)(?!.*[-+]\\s)(?!.*[-+.]$)[0-9a-zA-Z®ÁÉÍÑÓÚÜáéíñóúüÄÖŒßäöÀÂÆÇÈÊËÎÏÔÙÛŸàâæçèéêëîïôùûÿœ　-ゟ゠-ヿ一-鿿＀-￯ &+\\-[\\]'\".\\\\]{1,80}$","description":"The keyword as a shopper would type it. Stored lowercased; duplicates within the same list are merged."},"language":{"type":"string","pattern":"^[a-z]{2}-[A-Z]{2}$","description":"Language-country code of the keyword, like es-ES, en-GB or de-DE."},"epiniumScore":{"description":"Relevance from 1 (weak) to 5 (core keyword), the same stars the app shows. Omit to leave it unrated.","type":"integer","minimum":1,"maximum":5},"purpose":{"description":"What the keyword is for: SEO (listing content), PPC (advertising targets) or both. A new keyword defaults to both.","minItems":1,"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language"],"additionalProperties":false}},"negativeKeywords":{"description":"Keywords to keep away from, up to 50.","maxItems":50,"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string","minLength":1,"maxLength":80,"pattern":"^(?![-.])(?!.*\\s-)(?!.*[-+]\\s)(?!.*[-+.]$)[0-9a-zA-Z®ÁÉÍÑÓÚÜáéíñóúüÄÖŒßäöÀÂÆÇÈÊËÎÏÔÙÛŸàâæçèéêëîïôùûÿœ　-ゟ゠-ヿ一-鿿＀-￯ &+\\-[\\]'\".\\\\]{1,80}$","description":"The keyword as a shopper would type it. Stored lowercased; duplicates within the same list are merged."},"language":{"type":"string","pattern":"^[a-z]{2}-[A-Z]{2}$","description":"Language-country code of the keyword, like es-ES, en-GB or de-DE."},"epiniumScore":{"description":"Relevance from 1 (weak) to 5 (core keyword), the same stars the app shows. Omit to leave it unrated.","type":"integer","minimum":1,"maximum":5},"purpose":{"description":"What the keyword is for: SEO (listing content), PPC (advertising targets) or both. A new keyword defaults to both.","minItems":1,"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language"],"additionalProperties":false}},"products":{"description":"Ids of catalog products (`/v1/products` with `type` seller or vendor) the cluster groups. Every id must belong to the account; advertising products (`type` adv) are refused.","maxItems":1000,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"prompts":{"description":"Ids of custom prompts of the account (from `/v1/prompts`) that the SEO content generation of the cluster products follows. An id that does not belong to the account is refused.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"notes":{"nullable":true,"type":"string"},"positiveKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"negativeKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"protected":{"type":"boolean"},"productCount":{"type":"number"},"products":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","createdAt","updatedAt"],"additionalProperties":false}}]},"prompts":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","notes","positiveKeywords","negativeKeywords","protected","productCount","prompts","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/clusters/{id}":{"get":{"tags":["clusters"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"notes":{"nullable":true,"type":"string"},"positiveKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"negativeKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"protected":{"type":"boolean"},"productCount":{"type":"number"},"products":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","createdAt","updatedAt"],"additionalProperties":false}}]},"prompts":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","notes","positiveKeywords","negativeKeywords","protected","productCount","prompts","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Add or remove keywords and products of a cluster, or rename it","tags":["clusters"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New name.","type":"string","minLength":1,"maxLength":200},"addPositiveKeywords":{"description":"Positive keywords to add or update, matched by text. The list cannot exceed 100 afterwards.","maxItems":100,"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string","minLength":1,"maxLength":80,"pattern":"^(?![-.])(?!.*\\s-)(?!.*[-+]\\s)(?!.*[-+.]$)[0-9a-zA-Z®ÁÉÍÑÓÚÜáéíñóúüÄÖŒßäöÀÂÆÇÈÊËÎÏÔÙÛŸàâæçèéêëîïôùûÿœ　-ゟ゠-ヿ一-鿿＀-￯ &+\\-[\\]'\".\\\\]{1,80}$","description":"The keyword as a shopper would type it. Stored lowercased; duplicates within the same list are merged."},"language":{"type":"string","pattern":"^[a-z]{2}-[A-Z]{2}$","description":"Language-country code of the keyword, like es-ES, en-GB or de-DE."},"epiniumScore":{"description":"Relevance from 1 (weak) to 5 (core keyword), the same stars the app shows. Omit to leave it unrated.","type":"integer","minimum":1,"maximum":5},"purpose":{"description":"What the keyword is for: SEO (listing content), PPC (advertising targets) or both. A new keyword defaults to both.","minItems":1,"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language"],"additionalProperties":false}},"removePositiveKeywords":{"description":"Texts of positive keywords to remove. Unknown texts are ignored.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"addNegativeKeywords":{"description":"Negative keywords to add or update, matched by text. The list cannot exceed 50 afterwards.","maxItems":50,"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string","minLength":1,"maxLength":80,"pattern":"^(?![-.])(?!.*\\s-)(?!.*[-+]\\s)(?!.*[-+.]$)[0-9a-zA-Z®ÁÉÍÑÓÚÜáéíñóúüÄÖŒßäöÀÂÆÇÈÊËÎÏÔÙÛŸàâæçèéêëîïôùûÿœ　-ゟ゠-ヿ一-鿿＀-￯ &+\\-[\\]'\".\\\\]{1,80}$","description":"The keyword as a shopper would type it. Stored lowercased; duplicates within the same list are merged."},"language":{"type":"string","pattern":"^[a-z]{2}-[A-Z]{2}$","description":"Language-country code of the keyword, like es-ES, en-GB or de-DE."},"epiniumScore":{"description":"Relevance from 1 (weak) to 5 (core keyword), the same stars the app shows. Omit to leave it unrated.","type":"integer","minimum":1,"maximum":5},"purpose":{"description":"What the keyword is for: SEO (listing content), PPC (advertising targets) or both. A new keyword defaults to both.","minItems":1,"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language"],"additionalProperties":false}},"removeNegativeKeywords":{"description":"Texts of negative keywords to remove. Unknown texts are ignored.","maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"addProducts":{"description":"Ids of catalog products (`type` seller or vendor) to add. Every id must belong to the account; advertising products are refused and ids already in the cluster are ignored.","maxItems":1000,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"removeProducts":{"description":"Ids of catalog products to take out of the cluster.","maxItems":1000,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"addPrompts":{"description":"Ids of custom prompts of the account (from `/v1/prompts`) that the SEO content generation of the cluster products follows. An id that does not belong to the account is refused. Ids already in the cluster are ignored.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"removePrompts":{"description":"Ids of prompts to take out of the cluster. The prompts themselves are not deleted.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"notes":{"nullable":true,"type":"string"},"positiveKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"negativeKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"protected":{"type":"boolean"},"productCount":{"type":"number"},"products":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","createdAt","updatedAt"],"additionalProperties":false}}]},"prompts":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","notes","positiveKeywords","negativeKeywords","protected","productCount","prompts","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a keyword cluster","tags":["clusters"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/prompts":{"get":{"summary":"List the authenticated account's custom prompts","tags":["prompts"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the prompt name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Create a custom prompt","tags":["prompts"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":200,"description":"Name shown in Settings > Prompts of the Epinium app. At least 3 characters."},"instruction":{"type":"string","minLength":1,"maxLength":2000,"description":"What the AI must follow when it writes the listing content, in plain language: tone, structure, words to use or avoid. Up to 2000 characters. It is applied when content is generated, never on its own."},"fields":{"description":"Listing fields the prompt applies to: titleAndHighlights (title plus Item Highlights, generated together), product_description, bullet_point or generic_keyword (search terms). Omit it or send [] to use the prompt for every field.","maxItems":4,"type":"array","items":{"type":"string","enum":["titleAndHighlights","product_description","bullet_point","generic_keyword"]}}},"required":["name","instruction"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/prompts/{id}":{"get":{"tags":["prompts"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Rename a custom prompt or change its instruction or fields","tags":["prompts"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New name.","type":"string","minLength":3,"maxLength":200},"instruction":{"description":"New instruction, replacing the current one. Up to 2000 characters.","type":"string","minLength":1,"maxLength":2000},"fields":{"description":"New list of listing fields, replacing the current one. Send [] to use the prompt for every field.","maxItems":4,"type":"array","items":{"type":"string","enum":["titleAndHighlights","product_description","bullet_point","generic_keyword"]}}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/advertising-changes":{"get":{"summary":"List the changes Epinium pushed to Amazon for the authenticated account","tags":["advertising-changes"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"adgroup","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"entity","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"entity_type","in":"query","schema":{"type":"string","enum":["campaign","adgroup","target","productAd","portfolio"]}},{"name":"source","in":"query","schema":{"type":"string","enum":["front","workflow","public-api","mcp","system"]}},{"name":"result","in":"query","schema":{"type":"string","enum":["applied","failed"]}},{"name":"field","in":"query","schema":{"type":"string"}},{"name":"correlation_id","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"entity_type":{"type":"string","enum":["campaign","adgroup","target","productAd","portfolio"]},"entity_id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adgroup":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"field":{"type":"string"},"old_value":{},"new_value":{},"source":{"type":"string","enum":["front","workflow","public-api","mcp","system"]},"actor":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","apiKey","oauthClient","system"]},"id":{"type":"string"},"label":{"type":"string"}},"required":["type"],"additionalProperties":false},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"},"profile_id":{"nullable":true,"type":"string"},"ad_product":{"nullable":true,"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"correlation_id":{"nullable":true,"type":"string"}},"required":["id","at","entity_type","entity_id","campaign","adgroup","field","source","actor","result","error","profile_id","ad_product","correlation_id"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/tasks":{"get":{"summary":"List the authenticated account's tasks","tags":["tasks"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the task title. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","resolved","discarded"]}},{"name":"priority","in":"query","schema":{"type":"string","enum":["high","medium","low"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Create a task with its suggestions","tags":["tasks"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"priority":{"type":"string","enum":["high","medium","low"]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"items":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"entityModel":{"type":"string","enum":["products","campaigns","adgroups","targets","search_terms","product_ads"]},"displayName":{"type":"string","maxLength":200},"displayId":{"type":"string","maxLength":100},"problemLabel":{"type":"string","maxLength":200},"problemSeverity":{"type":"string","enum":["error","warning","info"]},"fieldName":{"type":"string","maxLength":100},"fieldPath":{"type":"string","maxLength":300},"valueType":{"type":"string","enum":["string","text","number","boolean","string_array","html"]},"currentValue":{},"suggestedValue":{}},"required":["entityId","entityModel"],"additionalProperties":false}}},"required":["title"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/tasks/{id}":{"get":{"tags":["tasks"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Change a task's metadata","tags":["tasks"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"priority":{"type":"string","enum":["high","medium","low"]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/tasks/{id}/resolve":{"post":{"summary":"Resolve or discard a task","tags":["tasks"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]}},"required":["action"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/tasks/{id}/apply":{"post":{"summary":"Apply a task's approved suggestions","tags":["tasks"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"maxItems":1000,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"enqueued":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"skipped":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bulk":{"nullable":true,"type":"string"}},"required":["applied","failed","enqueued","skipped","bulk"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/task-items":{"get":{"summary":"List the authenticated account's task items","tags":["task-items"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the item display name, display id and problem label. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"task","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"entityModel","in":"query","schema":{"type":"string","enum":["products","campaigns","adgroups","targets","search_terms","product_ads"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","rejected"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"task":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}]},"entityId":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"entityModel":{"type":"string","enum":["products","campaigns","adgroups","targets","search_terms","product_ads"]},"displayName":{"nullable":true,"type":"string"},"displayId":{"nullable":true,"type":"string"},"problemLabel":{"nullable":true,"type":"string"},"problemSeverity":{"nullable":true,"type":"string","enum":["error","warning","info"]},"fieldName":{"nullable":true,"type":"string"},"fieldPath":{"nullable":true,"type":"string"},"valueType":{"nullable":true,"type":"string","enum":["string","text","number","boolean","string_array","html"]},"currentValue":{},"suggestedValue":{},"appliedValue":{},"status":{"type":"string","enum":["pending","approved","rejected"]},"autoApplySkipped":{"nullable":true,"type":"boolean"},"applyError":{"nullable":true,"type":"string"},"appliedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","task","entityId","entityModel","displayName","displayId","problemLabel","problemSeverity","fieldName","fieldPath","valueType","currentValue","suggestedValue","appliedValue","status","autoApplySkipped","applyError","appliedAt","resolvedAt","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/task-items/{id}":{"get":{"tags":["task-items"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"task":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}]},"entityId":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"entityModel":{"type":"string","enum":["products","campaigns","adgroups","targets","search_terms","product_ads"]},"displayName":{"nullable":true,"type":"string"},"displayId":{"nullable":true,"type":"string"},"problemLabel":{"nullable":true,"type":"string"},"problemSeverity":{"nullable":true,"type":"string","enum":["error","warning","info"]},"fieldName":{"nullable":true,"type":"string"},"fieldPath":{"nullable":true,"type":"string"},"valueType":{"nullable":true,"type":"string","enum":["string","text","number","boolean","string_array","html"]},"currentValue":{},"suggestedValue":{},"appliedValue":{},"status":{"type":"string","enum":["pending","approved","rejected"]},"autoApplySkipped":{"nullable":true,"type":"boolean"},"applyError":{"nullable":true,"type":"string"},"appliedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","task","entityId","entityModel","displayName","displayId","problemLabel","problemSeverity","fieldName","fieldPath","valueType","currentValue","suggestedValue","appliedValue","status","autoApplySkipped","applyError","appliedAt","resolvedAt","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Approve or reject one suggestion","tags":["task-items"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["approved","rejected"]},"appliedValue":{}},"required":["status"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"},"autoApplySkipped":{"type":"boolean"}},"required":["id","result","error","autoApplySkipped"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/task-items/batch":{"post":{"summary":"Approve or reject many suggestions at once","tags":["task-items"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"status":{"type":"string","enum":["approved","rejected"]},"appliedValue":{}},"required":["id","status"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"},"autoApplySkipped":{"type":"boolean"}},"required":["id","result","error","autoApplySkipped"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows":{"get":{"description":"Filter by `description_key` to tell workflow types apart: `name` and `name_key` are NOT reliable discriminators because several templates share a display name. `template` filters by the global template a workflow was cloned from. Global templates themselves are never listed here — only the account's own workflows.","summary":"List the authenticated account's workflows","tags":["workflows"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the workflow name and description. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"template","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"description_key","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"The workflow is created PAUSED, so it does nothing until a human turns it on in the app — this endpoint cannot activate it, with or without a `schedule`. Sending `schedule` only says WHEN it would run once somebody enables it; it never makes it run. The graph must pass validation: on failure you get 422 with the same error list `validate` returns, and nothing is written. Requires the `workflows:write` scope.","summary":"Create a workflow, paused","tags":["workflows"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"nodes":{"minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","minLength":1},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"source":{"type":"string","minLength":1},"target":{"type":"string","minLength":1},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target"],"additionalProperties":false}},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"type":{"type":"string","enum":["number","boolean","string","select","multiselect","string-list"]},"value":{},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"nullable":true,"type":"boolean"}},"required":["key","type","value"]}},"schedule":{"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"timezone":{"nullable":true,"type":"string"}},"required":["type"]}},"required":["name","nodes","edges"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"422","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"node_id":{"nullable":true,"type":"string"},"edge_id":{"nullable":true,"type":"string"}},"required":["code","message","hint","node_id","edge_id"],"additionalProperties":false}},"guidance":{"type":"string"}},"required":["valid","errors"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}":{"get":{"description":"Returns the full definition: the node graph, and every configuration variable with its effective value. `overridden` on a variable tells you whether the customer set it or it still carries the template default — which is usually the question worth asking when auditing a setup.","summary":"Retrieve one workflow with its resolved configuration","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. A key that matches no entity is ignored silently and the full object comes back.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"description":"Deletes the workflow, its execution history, the payloads of those executions and its version snapshots. There is no undo and no bin: once gone, the record of what it did is gone with it. Requires the `workflows:write` scope.","summary":"Delete a workflow and everything under it","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"204":{"description":"204","content":{"application/json":{"schema":{}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"Editing the graph only works while the workflow is paused: doing it on one that is scheduled returns 409, and so does sending `schedule` for a workflow that is active at all. The one exception is `active: false` on its own, which is ALWAYS allowed — pausing can only make less happen on Amazon, and refusing it would leave a scheduled workflow impossible to edit through this API at all. Sending `active: true` turns the workflow on: from then on its schedule fires for real — because its next run moves real bids and a half-reviewed graph should not be what executes. Pause it in the app first. `nodes` and `edges` are replaced wholesale and must be sent together — a partial patch would leave edges pointing at nodes that no longer exist, so sending one without the other is a 400, as is an empty body. The graph must pass validation: on failure you get 422 and nothing is written. Requires the `workflows:write` scope.","summary":"Edit a paused workflow, or pause one","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"nodes":{"minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","minLength":1},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"source":{"type":"string","minLength":1},"target":{"type":"string","minLength":1},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target"],"additionalProperties":false}},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"type":{"type":"string","enum":["number","boolean","string","select","multiselect","string-list"]},"value":{},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"nullable":true,"type":"boolean"}},"required":["key","type","value"]}},"schedule":{"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"timezone":{"nullable":true,"type":"string"}},"required":["type"]},"active":{"type":"boolean"},"dry_run":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"422","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"node_id":{"nullable":true,"type":"string"},"edge_id":{"nullable":true,"type":"string"}},"required":["code","message","hint","node_id","edge_id"],"additionalProperties":false}},"guidance":{"type":"string"}},"required":["valid","errors"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/campaigns":{"get":{"description":"NOT simply the campaigns that link to the workflow. Membership is decided by three controls stored per campaign (force-include, force-exclude, global opt-out) combined with the workflow's own filter and its auto-selection setting. Each row carries a `gate` object saying why it is in, plus the campaign's effective AI configuration. When the set is empty, `empty_reason` names the cause: `manual-sin-enlaces` means the workflow is on manual selection with nothing linked — the state a workflow is BORN in, and the usual reason one runs nightly for weeks doing nothing. `filtro-vacio` means no campaign passes its own filter. `no-itera-campanas` means this workflow does not act on campaigns at all.","summary":"Campaigns this workflow actually processes","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"campaign_id":{"type":"string"},"name":{"type":"string"},"state":{"nullable":true,"type":"string"},"ad_product":{"nullable":true,"type":"string"},"config":{"type":"object","properties":{"objective_type":{"nullable":true,"type":"string"},"objective_value":{"nullable":true,"type":"number"},"min_bid":{"nullable":true,"type":"number"},"max_bid":{"nullable":true,"type":"number"},"placement_cap_percent":{"nullable":true,"type":"number"},"daily_budget":{"nullable":true,"type":"number"},"monthly_budget":{"nullable":true,"type":"number"},"ai_enabled":{"type":"boolean"},"optimizing_since":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["objective_type","objective_value","min_bid","max_bid","placement_cap_percent","daily_budget","monthly_budget","ai_enabled","optimizing_since"],"additionalProperties":false},"gate":{"type":"object","properties":{"linked":{"type":"boolean"},"excluded":{"type":"boolean"},"opt_out":{"type":"boolean"},"matched_own_filter":{"type":"boolean"}},"required":["linked","excluded","opt_out","matched_own_filter"],"additionalProperties":false}},"required":["id","campaign_id","name","state","ad_product","config","gate"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"empty_reason":{"nullable":true,"type":"string","enum":["manual-sin-enlaces","filtro-vacio","no-itera-campanas"]}},"required":["object","data","has_more","empty_reason"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/performance":{"get":{"description":"Aggregated over a required `start_date`/`end_date` window, restricted to the campaigns the workflow actually processes. Each row puts the configured `objective_type`/`objective_value` next to the realized metrics, which is how you judge whether the workflow is hitting its target. `optimizing_since` is when the workflow first touched that campaign for real — results before that date are NOT its doing, so a window straddling it will mislead you. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero.","summary":"Advertising performance of the campaigns this workflow optimizes","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per campaign, which is the row to compare against its objective. `daily` splits each campaign into one row per day with activity, but these rows carry no `date` field, so they cannot be told apart: for a dated daily series use `campaign-metrics` with `campaign` and `granularity=daily`. Calendar periods (`weekly`, `monthly`, `quarterly`, `yearly`) are not available on this route. `daily` has a shorter window cap than `total`.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"campaign":{"type":"string"},"campaign_name":{"nullable":true,"type":"string"},"currency":{"type":"string"},"cost":{"type":"string"},"sales":{"type":"string"},"impressions":{"type":"number"},"clicks":{"type":"number"},"orders":{"type":"number"},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"ctr":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"type":"number"},"objective_type":{"nullable":true,"type":"string"},"objective_value":{"nullable":true,"type":"number"},"optimizing_since":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["campaign","campaign_name","currency","cost","sales","impressions","clicks","orders","acos","roas","ctr","conversion_rate","objective_type","objective_value","optimizing_since"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/executions":{"get":{"description":"What the workflow has actually done, run by run. `status` tells them apart, and `partial` is its own outcome, not a shade of the other two: the graph finished but some items inside a forEach failed and the rest carried on, so neither \"it all worked\" nor \"nothing happened\" is true. `dry_run` says whether the run wrote anything at all — filter it out before drawing conclusions from a series. The per-node detail of a run is in its payloads.","summary":"Runs of a workflow, newest first","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"dry_run","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"workflow":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"status":{"type":"string","enum":["pending","running","completed","partial","failed","cancelled"]},"dry_run":{"type":"boolean"},"error":{"nullable":true,"type":"string"},"tokens_consumed":{"type":"number"},"node_result_count":{"type":"number"},"started_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"completed_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","workflow","status","dry_run","error","tokens_consumed","node_result_count","started_at","completed_at","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/executions/{executionId}/payloads":{"get":{"description":"The output every node left behind in that run — this is where a workflow's decisions actually are, one row per node and per forEach item. Read this, not the run itself, to answer what a workflow decided and why: the run document only carries the top-level nodes, and in this product the reasoning lives inside the forEach.\n\nIt takes two calls, on purpose. The first, with the default `data=none`, is the INDEX: every step with its `label`, and nothing else. A `label` starts with the CONTAINER — the forEach the work happened in — then the item, then the node that did it: `wf-foreach-targets-item-2-p9747-wf-calc-bid`. So `label_prefix` takes the container, not the node at the end. Read the index first and copy a prefix from it rather than composing one; a prefix that matches nothing is rejected and the error lists the ones that exist. Asking for `data=full` across a whole run of a catalogue-sized workflow returns millions of characters and overflows what a host will accept, which is why it is not the default. `type` separates a node's own decision (`nodeResult`) from the engine's scaffolding.","summary":"What each node produced in a run","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"executionId","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"label_prefix","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["subGraph","context","nodeResult"]}},{"name":"data","in":"query","schema":{"type":"string","enum":["none","full"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["subGraph","context","nodeResult"]},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}}},"required":["id","type","label"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflow-node-types":{"get":{"description":"Everything the workflow engine understands: the node types and what each is for, which fields their `data` needs and which the server fills in for you, the actions a node can run, the operators a condition accepts, and what a forEach can iterate over. Read it BEFORE building a graph - without it the only way to learn the shape is to read an existing workflow and infer, and an account with no workflow of the kind you need leaves you guessing. Identical for every account, so it is not charged.","summary":"What a workflow graph can be made of","tags":["workflows"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"node_types":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"purpose":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"filled_by_server":{"type":"boolean"},"default_value":{},"required":{"type":"boolean"},"description":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","object","array"]},"required":{"type":"boolean"},"description":{"type":"string"}},"required":["name","type","required","description"],"additionalProperties":false}}},"required":["name","filled_by_server","default_value"],"additionalProperties":false}},"source_handles":{"type":"array","items":{"type":"string"}}},"required":["type","purpose","fields","source_handles"],"additionalProperties":false}},"action_types":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"group":{"type":"string","enum":["general","campaign-optimizer"]},"config_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","object","array"]},"required":{"type":"boolean"},"description":{"type":"string"}},"required":["name","type","required","description"],"additionalProperties":false}}},"required":["action","group"],"additionalProperties":false}},"config_envelope":{"type":"string"},"condition_operators":{"type":"array","items":{"type":"string"}},"condition_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","object","array"]},"required":{"type":"boolean"},"description":{"type":"string"}},"required":["name","type","required","description"],"additionalProperties":false}},"for_each":{"type":"object","properties":{"modes":{"type":"array","items":{"type":"string"}},"collections":{"type":"array","items":{"type":"string"}}},"required":["modes","collections"],"additionalProperties":false}},"required":["node_types","action_types","config_envelope","condition_operators","condition_fields","for_each"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/versions":{"get":{"description":"Every create, clone, instantiation and edit leaves a version behind, and so does a restore — restoring is never a one-way trip. Versions EXPIRE, so an old workflow can show fewer than were actually made: a short list does not mean nobody touched it. `author` says where the change came from, which is what separates an edit made by an integration from one made by hand in Epinium. The graph is not here; read one version to see it.","summary":"Saved versions of a workflow, newest first","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"workflow":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"description":{"type":"string"},"active":{"type":"boolean"},"node_count":{"type":"number"},"author":{"nullable":true,"type":"object","properties":{"source":{"type":"string","enum":["app","public-api","mcp","chat"]},"credential_type":{"nullable":true,"type":"string","enum":["api_key","oauth"]}},"required":["source","credential_type"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","workflow","name","description","active","node_count","author","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/versions/{versionId}":{"get":{"description":"The full graph as it was when that version was saved. Read it before restoring: restoring replaces the live graph wholesale, and this is the only way to see what it would become.","summary":"One saved version, with its graph","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"versionId","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"workflow":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"description":{"type":"string"},"active":{"type":"boolean"},"node_count":{"type":"number"},"author":{"nullable":true,"type":"object","properties":{"source":{"type":"string","enum":["app","public-api","mcp","chat"]},"credential_type":{"nullable":true,"type":"string","enum":["api_key","oauth"]}},"required":["source","credential_type"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}}},"required":["id","workflow","name","description","active","node_count","author","created_at","nodes","edges","variables"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/versions/{versionId}/restore":{"post":{"description":"Replaces the live graph with the one from that version. It is an edit, so the same rule applies: a workflow that can fire on its own is refused with 409 — pause it first with `active: false`, restore, and turn it back on when the result is what you wanted. The state being replaced is snapshotted first, so a restore can itself be undone. Requires the `workflows:write` scope.","summary":"Put a saved version back","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"versionId","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/cost-estimate":{"get":{"description":"The same forecast the app shows in the workflow detail, so read it BEFORE `run` with `dry_run: false` on anything that touches a large catalogue. A row closes exactly: `estimated_items * tokens_per_item + loop_tokens = estimated_tokens`. Do NOT multiply by `billable_nodes_per_item` — it counts the nodes rather than pricing them, and a `create-task` does not cost the same as a plain action. What the number is worth depends on one flag. For the rows with `forecastable: true` it is an UPPER bound: it counts every item that matches today, and a run can process fewer. But a row with `forecastable: false` is a `forEach` whose size cannot be known until the run happens, and its cost is left OUT of the total — so if any row carries that flag the total is not an upper bound at all, it is incomplete, and the real cost can exceed it. A zero there means 'not forecast', never 'free'.","summary":"What running this workflow would cost, without running it","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"estimated_tokens":{"type":"number"},"breakdown":{"type":"array","items":{"type":"object","properties":{"node":{"type":"string"},"node_type":{"type":"string"},"label":{"type":"string"},"estimated_items":{"type":"number"},"billable_nodes_per_item":{"type":"number"},"tokens_per_item":{"type":"number"},"loop_tokens":{"type":"number"},"estimated_tokens":{"type":"number"},"forecastable":{"type":"boolean"}},"required":["node","node_type","estimated_items","billable_nodes_per_item","tokens_per_item","loop_tokens","estimated_tokens","forecastable"],"additionalProperties":false}}},"required":["estimated_tokens","breakdown"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/run":{"post":{"description":"Queues an execution and returns its id — it does NOT wait for it to finish, because a run over dozens of campaigns takes far longer than any tool call. Read the outcome afterwards with the executions and payloads of this same workflow. `dry_run` is required and has no default on purpose: a real run moves bids and budgets on Amazon, and a simulation walks the whole graph writing nothing, so which one you meant should never depend on a field you forgot. A paused workflow can still be simulated — that is the point, checking it before turning it on — but running it for real needs it active. Requires the `workflows:write` scope.","summary":"Run a workflow now, for real or as a simulation","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean"}},"required":["dry_run"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"execution":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"status":{"type":"string"},"dry_run":{"type":"boolean"}},"required":["execution","status","dry_run"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/validate":{"post":{"description":"Runs the same structural, connectivity and semantic rules that `create` and `update` enforce, and persists nothing. `name` is optional here, unlike in `create`: nothing is saved, so there is nothing to name. Each error carries a `hint` saying what to change. Use it to iterate on a graph before writing it: a rejected write costs you the same round-trip but leaves you guessing less if you validated first.","summary":"Check a workflow graph without saving it","tags":["workflows"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"nodes":{"minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","minLength":1},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"source":{"type":"string","minLength":1},"target":{"type":"string","minLength":1},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target"],"additionalProperties":false}},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"type":{"type":"string","enum":["number","boolean","string","select","multiselect","string-list"]},"value":{},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"nullable":true,"type":"boolean"}},"required":["key","type","value"]}},"schedule":{"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"timezone":{"nullable":true,"type":"string"}},"required":["type"]}},"required":["nodes","edges"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"node_id":{"nullable":true,"type":"string"},"edge_id":{"nullable":true,"type":"string"}},"required":["code","message","hint","node_id","edge_id"],"additionalProperties":false}},"guidance":{"type":"string"}},"required":["valid","errors"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/clone":{"post":{"description":"Copies the graph, the declared variables and the schedule of an existing workflow server-side, so the caller never resends them. Like `create`, the copy is PAUSED and this endpoint cannot turn it on. Use it to run the same logic with different values: `variables` takes only the keys you want to change, and every other one keeps the source value. Requires the `workflows:write` scope.","summary":"Copy an existing workflow, paused","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"variables":{"type":"object","additionalProperties":{}}},"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflow-templates":{"get":{"description":"The catalogue of automations Epinium publishes, filtered to the ones this account is allowed to use. These are NOT workflows of the account: they do nothing until you instantiate one, which gives the account its own paused copy. Requires the `workflows:read` scope.","summary":"List the workflow templates this account can instantiate","tags":["workflow-templates"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"node_count":{"type":"number"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","name","description","description_key","node_count","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflow-templates/{id}/instantiate":{"post":{"description":"Creates the account's own copy of a template, PAUSED, with the template's graph, variables and schedule already in place — turning it on is a human step in Epinium. Instantiating the same template twice is allowed and gives two independent copies, so check what the account already has first: `epinium_list_workflows` with `template` filters by the template a workflow came from. A template this account is not entitled to returns 403. Requires the `workflows:write` scope.","summary":"Create this account copy of a template","tags":["workflow-templates"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/platform-request":{"post":{"operationId":"PlatformRequestController_callPlatform","parameters":[],"responses":{"201":{"description":""}},"tags":["PlatformRequest"]}},"/v1/platform-request/docs/{platform}":{"get":{"operationId":"PlatformRequestController_platformDocs","parameters":[],"responses":{"200":{"description":""}},"tags":["PlatformRequest"]}},"/v1/platform-changes":{"get":{"operationId":"PlatformChangesController_","parameters":[],"responses":{"200":{"description":""}},"tags":["PlatformChanges"]}}},"info":{"title":"Epinium Public API","description":"","version":"1.0.0","contact":{}},"tags":[{"name":"me","description":"Describes the authenticated API key: its scopes and accessible accounts. No scope required — any valid key can call it."},{"name":"accounts","description":"Accounts this API key can operate on, selectable via the `Epinium-Account` header. Requires `connections:read`."},{"name":"connections","description":"The authenticated account's data source connections. Requires `connections:read`."},{"name":"products","description":"The authenticated account's catalog products. Requires `catalog:read`."},{"name":"product-costs","description":"Set a product's unit cost and shipping cost. Requires `costs:write` - a scope of its own, not `catalog:write`: reading the costs this writes is part of `/v1/pnl/*`, gated by `catalog:read` and plan, not by this one."},{"name":"amazon-seller-products","description":"The authenticated account's Amazon Seller Central product listings. Requires `catalog:read`."},{"name":"amazon-vendor-products","description":"The authenticated account's Amazon Vendor Central product listings. Requires `catalog:read`."},{"name":"amazon-advertising-products","description":"The authenticated account's Amazon advertising products. Requires `catalog:read`."},{"name":"seller-product-metrics","description":"Seller Central sales and traffic per product, aggregated from the account's report history. Requires `catalog:read`."},{"name":"vendor-product-metrics","description":"Vendor Central sales per product, split by manufacturing and sourcing, aggregated from the account's report history. Requires `catalog:read`."},{"name":"pnl","description":"The authenticated account's P&L with product cost (COGS), from the same data as the Rentabilidad screen. Unlike every other resource in this API, amounts ARE converted into the `currency` you request. Free and Guru plans receive the same shape with product cost always `0`. Requires `catalog:read`."},{"name":"product-brands","description":"Brands present in the authenticated account's catalog. Requires `catalog:read`. Sparse fieldsets use `fields[brand]` — keyed by the entity type (`brand`, the same one `expand[]=brand` and a product's `brand` field use), not by the resource name."},{"name":"countries","description":"Amazon marketplace countries. Requires `catalog:read`."},{"name":"clusters","description":"The authenticated account's keyword clusters. Requires `catalog:read`; creating and editing them requires `catalog:write`."},{"name":"prompts","description":"The authenticated account's custom prompts: the instructions Epinium's AI follows when it writes listing content, linked to keyword clusters. Requires `catalog:read`; creating and editing them requires `catalog:write`."},{"name":"campaigns","description":"The authenticated account's advertising campaigns. Requires `campaigns:read`."},{"name":"campaign-metrics","description":"Advertising performance per campaign, aggregated from the account's report history. Requires `campaigns:read`."},{"name":"portfolios","description":"The authenticated account's portfolios and the budget cap each one puts on its campaigns. Requires `campaigns:read`; writing requires `campaigns:write`."},{"name":"adgroups","description":"The authenticated account's ad groups. Requires `campaigns:read`."},{"name":"adgroup-metrics","description":"Performance per ad group over a date range."},{"name":"targets","description":"The authenticated account's advertising targets. Requires `campaigns:read`."},{"name":"target-metrics","description":"Performance per target, with its keyword and match type."},{"name":"product-ads","description":"The authenticated account's advertising product ads. Requires `campaigns:read`."},{"name":"product-ad-metrics","description":"Performance per advertised product, with its ASIN."},{"name":"search-terms","description":"The authenticated account's advertising search terms. Requires `campaigns:read`."},{"name":"search-term-metrics","description":"Performance per shopper query, with its text and matching target."},{"name":"advertising-changes","description":"Every change Epinium pushed to Amazon for the authenticated account - from the app, a workflow, an internal job or this API - including the ones Amazon rejected. Requires `campaigns:read`."},{"name":"tasks","description":"The authenticated account's tasks. Requires `tasks:read`."},{"name":"task-items","description":"Individual suggestions within a task. Requires `tasks:read`."},{"name":"skills","description":"Catalog of validated marketing playbooks, served from memory and shared by every account. Requires `skills:read`."},{"name":"workflows","description":"The authenticated account's automation workflows, the campaigns they process and those campaigns' performance. Requires `workflows:read`."},{"name":"workflow-templates","description":"The catalogue of automations Epinium publishes, and the route to create this account's own copy of one. Which templates an account sees depends on its feature flags. Requires `workflows:read`; instantiating also requires `workflows:write`."}],"servers":[],"components":{"schemas":{},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Client API key (POST /api-keys). Send as `Authorization: Bearer epk_live_...`."}}},"security":[{"bearer":[]}]}