Amazon Ads API MCP

{"components":{"parameters":{"adGroupId":{"description":"The identifier of a valid ad group.","in":"path","name":"adGroupId","required":true,"schema":{"type":"number"}},"adGroupIdFilter":{"description":"Restricts results to keywords associated with ad groups specified by identifier in the comma-delimited list.","in":"query","name":"adGroupIdFilter","required":false,"schema":{"type":"string"}},"adId":{"description":"A product ad identifier.","in":"path","name":"adId","required":true,"schema":{"type":"number"}},"adIdFilter":{"description":"Restricts results to product ads associated with the product ad identifiers specified in the comma-delimited list.","in":"query","name":"adIdFilter","required":false,"schema":{"type":"string"}},"adStateFilter":{"description":"Filters results to ad groups with state matching the comma-delimited list.","in":"query","name":"adStateFilter","schema":{"enum":["enabled","paused","archived","enabled, paused","enabled, archived","paused, archived","enabled, paused, archived"],"type":"string"}},"campaignIdFilter":{"description":"A comma-delimited list of campaign identifiers.","in":"query","name":"campaignIdFilter","required":false,"schema":{"type":"string"}},"campaignType":{"description":"Restricts results to ad groups within campaign types specified in comma-separated list.","in":"query","name":"campaignType","required":false,"schema":{"type":"string"}},"clientHeader":{"description":"The identifier of a client associated with a \"Login with Amazon\" developer account.","in":"header","name":"Amazon-Advertising-API-ClientId","required":true,"schema":{"type":"string"}},"count":{"description":"Number of records to include in the paged response. Defaults to max page size of 5000.","in":"query","name":"count","required":false,"schema":{"type":"number"}},"keywordIdFilter":{"description":"Restricts results to keywords associated with campaigns specified by identifier in the comma-delimited list.","in":"query","name":"keywordIdFilter","required":false,"schema":{"type":"string"}},"keywordText":{"description":"Restricts results to keywords that match the specified text exactly.","in":"query","name":"keywordText","schema":{"type":"string"}},"locale":{"description":"Restricts results to keywords associated with locale.","in":"query","name":"locale","required":false,"schema":{"type":"string"}},"matchTypeFilter":{"description":"Restricts results to keywords with match types within the specified comma-separated list. For more information, see [match types](https://advertising.amazon.com/help#GHTRFDZRJPW6764R) in the Amazon Ads support center.","in":"query","name":"matchTypeFilter","schema":{"enum":["broad","phrase","exact"],"type":"string"}},"maxNumSuggestions":{"description":"The maximum number of suggested keywords for the response.","in":"query","name":"maxNumSuggestions","schema":{"default":100,"maximum":1000,"minimum":1,"type":"integer"}},"name":{"description":"Restricts results to campaigns with the specified name.","in":"query","name":"name","required":false,"schema":{"type":"string"}},"negativeAdGroupIdFilter":{"description":"Restricts results to negative keywords associated with ad groups specified by identifier in the comma-delimited list.","in":"query","name":"adGroupIdFilter","required":false,"schema":{"type":"string"}},"negativeCampaignIdFilter":{"description":"Restricts results to negative keywords associated with campaigns specified by identifier in the comma-delimited list.","in":"query","name":"campaignIdFilter","required":false,"schema":{"type":"string"}},"negativeKeywordIdFilter":{"description":"Restricts results to negative keywords associated with campaigns specified by identifier in the comma-delimited list.","in":"query","name":"keywordIdFilter","required":false,"schema":{"type":"string"}},"negativeKeywordText":{"description":"Restricts results to negative keywords that match the specified text.","in":"query","name":"keywordText","schema":{"type":"string"}},"negativeMatchTypeFilter":{"description":"Restricts results to negative keywords with match types within the specified comma-separated list. For more information, see [match types](https://advertising.amazon.com/help#GHTRFDZRJPW6764R) in the Amazon Ads support center.","in":"query","name":"matchTypeFilter","schema":{"enum":["negativePhrase","negativeExact"],"type":"string"}},"negativeStateFilter":{"description":"Restricts results to negative resources with state within the specified comma-separated list. Default includes all.","in":"query","name":"stateFilter","required":false,"schema":{"enum":["enabled","archived"],"type":"string"}},"portfolioIdFilter":{"description":"A comma-delimited list of portfolio identifiers.","in":"query","name":"portfolioIdFilter","required":false,"schema":{"type":"string"}},"profileHeader":{"description":"The identifier of a profile associated with the advertiser account. Use `GET` method on Profiles resource to list profiles associated with the access token passed in the HTTP Authorization header.","in":"header","name":"Amazon-Advertising-API-Scope","required":true,"schema":{"type":"string"}},"startIndex":{"description":"0-indexed record offset for the result set.","in":"query","name":"startIndex","schema":{"default":0,"type":"number"}},"stateFilter":{"description":"Restricts results to resources with state within the specified comma-separated list.","in":"query","name":"stateFilter","required":false,"schema":{"enum":["enabled","paused","archived","enabled, paused","enabled, archived","paused, archived","enabled, paused, archived"],"type":"string"}},"targetId":{"description":"The target identifier.","in":"path","name":"targetId","required":true,"schema":{"type":"number"}},"targetIdFilter":{"description":"A comma-delimited list of target identifiers.","in":"query","name":"targetIdFilter","schema":{"type":"string"}}},"responses":{"BadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad request."},"InvalidQueryParam":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"One or more query parameters contained an invalid value."},"NotAcceptable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"One or more values specified for a parameter was not within the specified acceptable range."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The requested resource was not found."},"ResourceNotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The requested resource was not found."},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized."},"UnprocessableEntity":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"An invalid parameter was specified."}},"schemas":{"AdGroupBidRecommendationsResponse":{"properties":{"adGroupId":{"description":"The identifier of the ad group.","type":"number"},"suggestedBid":{"$ref":"#/components/schemas/SuggestedBid"}}},"AdGroupSuggestedKeywordsResponse":{"properties":{"adGroupId":{"description":"The ad group identifier.","type":"number"},"suggestededKeywords":{"description":"An array of suggested keywords.","items":{"properties":{},"type":"string"},"type":"array"}}},"AdGroupSuggestedKeywordsResponseEx":{"properties":{"adGroupId":{"description":"The ad group identifier.","type":"number"},"bid":{"description":"The suggested bid for the suggested keyword. Note that this field will not be included in the response if the `suggestBids` query parameter is set to `no` in the request.","type":"number"},"campaignId":{"description":"The campaign identifier.","type":"number"},"keywordText":{"description":"The suggested keyword.","type":"string"},"matchType":{"$ref":"#/components/schemas/MatchType"},"state":{"description":"The state of the ad for which the keyword is suggested.","enum":["enabled","paused"],"type":"string"}}},"BidRecommendationsResponse":{"properties":{"adGroupId":{"description":"The identifier of the ad group that the recommendations are associated with.","type":"string"},"recommendations":{"description":"An array of bid recommendation objects.","items":{"properties":{"code":{"enum":["SUCCESS","NOT_FOUND"],"type":"string"},"keyword":{"type":"string"},"matchType":{"$ref":"#/components/schemas/MatchType"},"suggestedBid":{"$ref":"#/components/schemas/SuggestedBid"}}},"type":"array"}}},"BulkGetAsinSuggestedKeywordsResponse":{"items":{"properties":{"keywordText":{"description":"The keyword text.","properties":{},"type":"string"},"matchType":{"$ref":"#/components/schemas/MatchType","properties":{}}},"type":"object"},"type":"array"},"Error":{"properties":{"code":{"description":"An enumerated error for machine use.","readOnly":true,"type":"string"},"details":{"description":"A human-readable description of the error.","readOnly":true,"type":"string"}}},"GetAsinSuggestedKeywordsResponse":{"properties":{"asin":{"description":"The ASIN for which keywords are suggested.","type":"string"},"suggestedKeywords":{"description":"The list of suggested keywords.","items":{"properties":{"keywordText":{"type":"string"},"matchType":{"$ref":"#/components/schemas/MatchType"}},"type":"object"},"type":"array"}}},"KeywordBidRecommendationsData":{"properties":{"adGroupId":{"description":"The identifier of the ad group that the keywords are associated with.","type":"number"},"keywords":{"description":"An array of keyword data objects.","items":{"properties":{"keyword":{"description":"The keyword text.","type":"string"},"matchType":{"$ref":"#/components/schemas/MatchType"}},"type":"object"},"maxItems":5000,"minItems":0,"type":"array"}}},"KeywordBidRecommendationsResponse":{"properties":{"adGroupId":{"description":"The identifier of the ad group that the bid is associated with.","type":"number"},"keywordId":{"description":"The identifier of the keyword that the bid is associated with.","type":"number"},"suggestedBid":{"$ref":"#/components/schemas/SuggestedBid"}}},"MatchType":{"description":"The type of match. For more information, see [match types](https://advertising.amazon.com/help#GHTRFDZRJPW6764R) in the Amazon Ads support center.","enum":["exact","phrase","broad"],"type":"string"},"SnapshotRequest":{"properties":{"stateFilter":{"enum":["enabled","paused","archived","enabled, paused","enabled, archived","paused, archived","enabled, paused, archived"],"type":"string"}}},"SnapshotResponse":{"properties":{"recordType":{"description":"The record type of the report.","enum":["campaigns","adGroups","keywords","negativeKeywords","campaignNegativeKeywords","productAds","targets","negativeTargets"],"type":"string"},"snapshotId":{"description":"The snapshot identifier.","type":"string"},"status":{"description":"The generation status of the snapshot.","enum":["IN_PROGRESS","SUCCESS","FAILURE"],"type":"string"}}},"SuggestedBid":{"description":"Information about the recommended bid.","properties":{"rangeEnd":{"description":"The upper bound bid recommendation.","type":"number"},"rangeStart":{"description":"The lower bound bid recommendation.","type":"number"},"suggested":{"description":"The bid recommendation.","type":"number"}},"type":"object"},"TargetingExpressionPredicate":{"properties":{"type":{"description":"The type of targeting expression. You can specify values for the following predicates:\n| Predicate | Description |\n| --- | --- |\n| `asinCategorySameAs` | Negatively Target the same category as the cat...","enum":["asinCategorySameAs","asinBrandSameAs","asinPriceLessThan","asinPriceBetween","asinPriceGreaterThan","asinReviewRatingLessThan","asinReviewRatingBetween","asinReviewRatingGreaterThan","asinSameAs","queryBroadRelMatches","queryHighRelMatches","asinSubstituteRelated","asinAccessoryRelated","asinAgeRangeSameAs","asinGenreSameAs","asinIsPrimeShippingEligible","asinExpandedFrom","queryExactMatches","queryPhraseMatches","queryBroadMatches"],"type":"string"},"value":{"description":"The expression value","type":"string"}}}},"securitySchemes":{"bearer":{"scheme":"bearer","type":"http"}}},"info":{"title":"Amazon Ads API - Sponsored Products","version":"2.0"},"openapi":"3.0.2","paths":{"/v2/sp/adGroups/{adGroupId}/bidRecommendations":{"get":{"description":"**Deprecation notice: This endpoint will be deprecated on March 27, 2024. Use [theme-based bid recommendations](/API/docs/en-us/sponsored-products/3-0/openapi/prod#/ThemeBasedBidRecommendation/GetThemeBasedBidRecommendationForAdGroup_v1) going forward.**","operationId":"getAdGroupBidRecommendations","parameters":[{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/profileHeader"},{"description":"The identifier of an existing ad group.","in":"path","name":"adGroupId","required":true,"schema":{"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdGroupBidRecommendationsResponse"}}},"description":"Success."},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Either the specified ad group identifier was not found, or the specified ad group was found but no associated bid was found."}},"summary":"Gets a bid recommendation for an ad group. [PLANNED DEPRECATION 3/27/2024]","tags":["Bid recommendations"]}},"/v2/sp/adGroups/{adGroupId}/suggested/keywords":{"get":{"operationId":"getAdGroupSuggestedKeywords","parameters":[{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/profileHeader"},{"$ref":"#/components/parameters/adGroupId"},{"$ref":"#/components/parameters/maxNumSuggestions"},{"$ref":"#/components/parameters/adStateFilter"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdGroupSuggestedKeywordsResponse"}}},"description":"Success."},"400":{"$ref":"#/components/responses/ResourceNotFound"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Gets suggested keywords for the specified ad group.","tags":["Suggested keywords"]}},"/v2/sp/adGroups/{adGroupId}/suggested/keywords/extended":{"get":{"operationId":"getAdGroupSuggestedKeywordsEx","parameters":[{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/profileHeader"},{"$ref":"#/components/parameters/adGroupId"},{"$ref":"#/components/parameters/maxNumSuggestions"},{"description":"Set to `yes` to include a suggest bid for the suggested keyword in the response. Otherwise, set to `no`.","in":"query","name":"suggestBids","schema":{"default":"no","enum":["yes","no"],"type":"string"}},{"$ref":"#/components/parameters/adStateFilter"}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/AdGroupSuggestedKeywordsResponseEx"},"type":"array"}}},"description":"Success."},"400":{"$ref":"#/components/responses/InvalidQueryParam"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Gets suggested keywords with extended data for the specified ad group.","tags":["Suggested keywords"]}},"/v2/sp/asins/suggested/keywords":{"post":{"description":"Suggested keywords are returned in an array ordered by descending effectiveness.","operationId":"bulkGetAsinSuggestedKeywords","parameters":[{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/profileHeader"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"asins":{"description":"A list of ASINs.","items":{"type":"string"},"type":"array"},"maxNumSuggestions":{"default":100,"description":"The maximum number of suggested keywords in the response.","maxItems":1000,"minItems":1,"type":"integer"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkGetAsinSuggestedKeywordsResponse"}}},"description":"Success."},"400":{"$ref":"#/components/responses/InvalidQueryParam"}},"summary":"Gets suggested keyword for a specified list of ASINs.","tags":["Suggested keywords"]}},"/v2/sp/asins/{asinValue}/suggested/keywords":{"get":{"description":"Suggested keywords are returned in an array ordered by descending effectiveness.","operationId":"getAsinSuggestedKeywords","parameters":[{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/profileHeader"},{"description":"An ASIN.","in":"path","name":"asinValue","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/maxNumSuggestions"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAsinSuggestedKeywordsResponse"}}},"description":"Success."},"400":{"$ref":"#/components/responses/InvalidQueryParam"}},"summary":"Gets suggested keywords for the specified ASIN.","tags":["Suggested keywords"]}},"/v2/sp/keywords/bidRecommendations":{"post":{"description":"**Deprecation notice: This endpoint will be deprecated on March 27, 2024. Use [theme-based bid recommendations](/API/docs/en-us/sponsored-products/3-0/openapi/prod#/ThemeBasedBidRecommendation/GetThemeBasedBidRecommendationForAdGroup_v1) going forward.**","operationId":"createKeywordBidRecommendations","parameters":[{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/profileHeader"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordBidRecommendationsData"}}},"description":"An array of keyword bid recommendation objects."},"responses":{"207":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BidRecommendationsResponse"}}},"description":"Multi-status."},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Gets bid recommendations for keywords. [PLANNED DEPRECATION 3/27/2024]","tags":["Bid recommendations"]}},"/v2/sp/keywords/{keywordId}/bidRecommendations":{"get":{"description":"**Deprecation notice: This endpoint will be deprecated on March 27, 2024. Use [theme-based bid recommendations](/API/docs/en-us/sponsored-products/3-0/openapi/prod#/ThemeBasedBidRecommendation/GetThemeBasedBidRecommendationForAdGroup_v1) going forward.**","operationId":"getKeywordBidRecommendations","parameters":[{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/profileHeader"},{"description":"The identifier of an existing keyword.","in":"path","name":"keywordId","required":true,"schema":{"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordBidRecommendationsResponse"}}},"description":"Success."},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Gets a bid recommendation for a keyword. [PLANNED DEPRECATION 3/27/2024]","tags":["Bid recommendations"]}},"/v2/sp/snapshots/{snapshotId}":{"get":{"description":"**Note: Snapshots APIs are deprecated and will be shut off on October 15, 2024. For replacement functionality, see the [exports](guides/exports/overview) API.","operationId":"getSnapshotStatus","parameters":[{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/profileHeader"},{"description":"The snapshot identifier.","in":"path","name":"snapshotId","required":true,"schema":{"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotResponse"}}},"description":"Success."},"307":{"description":"Temporary redirect."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Get the status of a requested snapshot","tags":["Snapshots"]}},"/v2/sp/snapshots/{snapshotId}/download":{"get":{"description":"**Note: Snapshots APIs are deprecated and will be shut off on October 15, 2024. For replacement functionality, see the [exports](guides/exports/overview) API.","operationId":"downloadSnapshot","parameters":[{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/profileHeader"},{"description":"The snapshot identifier.","in":"path","name":"snapshotId","required":true,"schema":{"type":"number"}}],"responses":{"307":{"description":"Successful operation."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Download requested snapshot","tags":["Snapshots"]}},"/v2/sp/targets/bidRecommendations":{"post":{"operationId":"getBidRecommendations","requestBody":{"content":{"application/json":{"schema":{"properties":{"adGroupId":{"description":"The ad group identifier.","type":"number"},"expressions":{"description":"The list of targeting expressions.","items":{"items":{"$ref":"#/components/schemas/TargetingExpressionPredicate"},"type":"array"},"type":"array"}},"type":"object"}}},"description":"An ad group identifier and list of associated targeting expressions for which to generate bid recommendations. Note that targeting expressions are required to be of the same type. That is, all targeting expressions in the list must be one of **keyword**, **product**, or **auto** target types."},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"adGroupId":{"description":"The ad group identifier.","type":"number"},"recommendations":{"description":"The list of recommended bids with associated targeting expressions.","items":{"properties":{"code":{"description":"The response code.","enum":["SUCCESS","INVALID_ARGUMENT","NOT_FOUND","INTERNAL_ERROR","SERVER_IS_BUSY","UNAUTHORIZED"],"type":"string"},"expression":{"$ref":"#/components/schemas/TargetingExpressionPredicate"},"suggestedBid":{"$ref":"#/components/schemas/SuggestedBid"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"Success."},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Gets a list of bid recommendations for keyword, product, or auto targeting expressions.","tags":["Bid recommendations"]}},"/v2/sp/{recordType}/snapshot":{"post":{"description":"**Note: Snapshots APIs are deprecated and will be shut off on October 15, 2024. For replacement functionality, see the [exports](guides/exports/overview) API.","operationId":"requestSnapshot","parameters":[{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/profileHeader"},{"description":"The type of entity for which the snapshot is generated.","in":"path","name":"recordType","required":true,"schema":{"enum":["campaigns","adGroups","keywords","negativeKeywords","campaignNegativeKeywords","productAds","targets","negativeTargets"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotResponse"}}},"description":"Success."},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"Request a snapshot","tags":["Snapshots"]}}},"servers":[{"url":"https://advertising-api.amazon.com"}],"tags":[{"name":"Bid recommendations"},{"name":"Suggested keywords"},{"name":"Snapshots"}]}