Recommendations API

Download OpenAPI specification:Download

API Reference

Recommendations API are based on REST. This describes the resources that make up the official Adobe Target Recommendations API. The resources are designated by nouns or objects in the world of Recommendations like a feed or a design. The functionalities or operations on resources are designated by HTTP methods in each resource request.

Getting Started

A Recommendations API call looks like this:

curl -X POST \{{tenantId}}/target/recs/collections \
-H 'Accept: application/' \
-H 'Authorization: Bearer {{bearerToken}}' \
-H 'Content-Type: application/' \
-H 'X-Api-Key: {{xApiKey}}' \
-d '{
  "name": "Backpacking Tents",
  "rules": [
      "id": {
        "contains": [

The tenantId is your Adobe Experience Cloud tenant ID. It is present as a subdomain of your Experience Cloud URL. For example, if your Experience Cloud URL is or, the tenant ID is piedpiper.

bearerToken and xApiKey are security token variables explained below in Authentication.


  • These APIs do not allow you to interact with resources created in the Recommendations Classic.
  • Resources can not be deleted until they are no longer referenced by any other resources. For example, a criteria cannot be deleted if its being used in a recommendation activity. It can only be deleted if its removed from from wherever it is used.
  • This documentation does not include following APIs:
    • Entity Recommendation Download (legacy): To download CSV containing entity recommendations.
    • Custom Algorithm Upload (legacy): To upload custom algorithm feed through POST request.
    • Exclusions
    • Feeds


All Recommendations API requests are available in a Postman collection. Click the "Run in Postman" button to download the collection as a JSON file, then import it in Postman. Note this collection references a Postman environment, which is available from the Adobe I/O console integration page for your specific integration.

Run in Postman


Bearer Token

This API requires a bearer token for authentication and an API Key for authorization. To obtain them, you must create an integration in the Adobe I/O Console. Refer How to set up Adobe IO Authentication - Step by Step for information on creating the integration and obtaining a bearer token.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"


This API requires an API key for authorization and bearer token for authentication. The API Key is obtained when creating an integration in the Adobe I/O Console. Refer How to set up Adobe IO Authentication - Step by Step for information on creating the integration.

Security Scheme Type API Key
Header parameter name: X-Api-Key


A collection is a set of items that are eligible for a recommendation. It is defined by a set of membership rules. If an item satisfies these rules, it is a member of the collection.

List collections

Gets all available collections.

query Parameters
integer <int32> (offset)

Number of resources to skip from start in the server list. If not specified, the response list will start from first available resource.

integer <int32> (limit)

Number of resources to request. If not specified, the response will include all available resources.


Response samples

Content type

A response body example of a list containing 2 collections.

  • "offset": 0,
  • "limit": 2147483647,
  • "total": 2,
  • "list": [

Create collection

Creates a new collection as specified by the rules provided and returns the newly created collection definition.

Request Body schema: application/

Collection to be created/updated

string <= 250 characters

Unique name of the collection.

Array of objects (RestBasicMatcher) [ 1 .. 1000 ] items

Array of rules containing attribute : operation pairs.

The attribute is any valid entity attribute. It is a required field and it should not be more than 100 characters.

The operation is a pair of operator and operand values. The operator can be one of:

  • Numeric operators: greaterOrEquals, lesserOrEquals
  • String operators: startsWith, endsWith, contains, doesNotContain
  • Alphanumeric operators: equals, notEquals, valueIsPresent, valueIsNotPresent

The other part of operation, operand values, is an array of values. Each value cannot be more than 250 characters. There must be atleast 1 value and no more than 1000 values. Operand values are not required when operator is either valueIsPresent or valueIsNotPresent. Numeric operators accept integer or floating point operand values.


Request samples

Content type

A request body example of a collection object to be created/updated.

  • "name": "Backpacking Tents",
  • "rules": [

Response samples

Content type

A response body example of a collection object.

  • "id": 1,
  • "name": "Backpacking Tents",
  • "rules": [

Get collection