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 \
https://mc.adobe.io/{{tenantId}}/target/recs/collections \
-H 'Accept: application/vnd.adobe.target.v1+json' \
-H 'Authorization: Bearer {{bearerToken}}' \
-H 'Content-Type: application/vnd.adobe.target.v1+json' \
-H 'X-Api-Key: {{xApiKey}}' \
-d '{
  "name": "Backpacking Tents",
  "rules": [
    {
      "id": {
        "contains": [
          "backpacking"
        ]
      }
    }
  ]
}'

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 piedpiper.experiencecloud.adobe.com or piedpiper.marketing.adobe.com, the tenant ID is piedpiper.

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

Limitations

  • 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

Postman

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

Authentication

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"

API Key

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

Collections

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

get /collections

Adobe I/O gateway

https://mc.adobe.io/{tenantId}/target/recs/collections

Gets all available collections.

Authorizations:
query Parameters
offset
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.

limit
integer <int32> (limit)

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

Responses

200

Successful request with list of collection resources in response

Response samples

Content type
application/vnd.adobe.target.v1+json;charset=UTF-8

A response body example of a list containing 2 collections.

Copy
Expand all Collapse all
{
  • "offset": 0,
  • "limit": 2147483647,
  • "total": 2,
  • "list":
    [
    ]
}

Create collection

post /collections

Adobe I/O gateway

https://mc.adobe.io/{tenantId}/target/recs/collections

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

Authorizations:
Request Body schema: application/vnd.adobe.target.v1+json

Collection to be created/updated

name
required
string <= 250 characters

Unique name of the collection.

rules
required
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.

Responses

201

Collection resource created with resource definition in response

Request samples

Content type
application/vnd.adobe.target.v1+json

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

Copy
Expand all Collapse all
{
  • "name": "Backpacking Tents",
  • "rules":
    [
    ]
}

Response samples

Content type
application/vnd.adobe.target.v1+json;charset=UTF-8

A response body example of a collection object.

Copy
Expand all Collapse all
{
  • "id": 1,
  • "name": "Backpacking Tents",
  • "rules":
    [
    ]
}

Get collection

get /collections/{id}

Adobe I/O gateway

https://mc.adobe.io/{tenantId}/target/recs/collections/{id}

Gets the collection with the given ID.

Authorizations:
query Parameters
limit
integer <int32> (limit)

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

Responses

200

Successful request with collection resource in response

Response samples

Content type
application/vnd.adobe.target.v1+json;charset=UTF-8

A response body example of a collection object.

Copy
Expand all Collapse all
{
  • "id": 1,
  • "name": "Backpacking Tents",
  • "rules":
    [
    ]
}

Edit collection

put /collections/{id}

Adobe I/O gateway

https://mc.adobe.io/{tenantId}/target/recs/collections/{id}

Updates the collection with new name and/or new rules as specified and returns the updated collection definition.

Authorizations:
query Parameters
limit
integer <int32> (limit)

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

Request Body schema: application/vnd.adobe.target.v1+json

Collection to be created/updated

name
required
string <= 250 characters

Unique name of the collection.

rules
required
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.

Responses

200

Successful request with updated collection resource in response

Request samples

Content type
application/vnd.adobe.target.v1+json

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

Copy
Expand all Collapse all
{
  • "name": "Backpacking Tents",
  • "rules":
    [
    ]
}

Response samples

Content type
application/vnd.adobe.target.v1+json;charset=UTF-8

A response body example of a collection object.

Copy
Expand all Collapse all
{
  • "id": 1,
  • "name": "Backpacking Tents",
  • "rules":
    [
    ]
}

Delete collection

delete /collections/{id}

Adobe I/O gateway

https://mc.adobe.io/{tenantId}/target/recs/collections/{id}

Deletes the collection referenced by the given ID.

Authorizations:
query Parameters
limit
integer <int32> (limit)

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

Responses

200

Successful request with deleted collection resource in response

Response samples

Content type
application/vnd.adobe.target.v1+json;charset=UTF-8

A response body example of a collection object.

Copy
Expand all Collapse all
{
  • "id": 1,
  • "name": "Backpacking Tents",
  • "rules":
    [
    ]
}

Criteria

Criteria are rules that determine which items to recommend based on a predetermined set of visitor behaviors. Criteria are categorized into different groups depending on the recommendation key and recommendation logic. These groups are: category, item, recent, popularity, profile attribute, custom.

List criteria

get /criteria

Adobe I/O gateway

https://mc.adobe.io/{tenantId}/target/recs/criteria

Gets all available criteria.

Authorizations:
query Parameters
offset
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.

limit
integer <int32> (limit)

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

Responses

200

Successful request with list of criteria resources in response

Response samples

Content type
application/vnd.adobe.target.v1+json;charset=UTF-8

A response body example of a list containing 3 criteria.

Copy
Expand all Collapse all
{
  • "offset": "2,",
  • "limit": "2147483647,",
  • "total": 3,
  • "list":
    [
    ]
}

Get criteria

get /criteria/{id}

Adobe I/O gateway

https://mc.adobe.io/{tenantId}/target/recs/criteria/{id}

Gets minimal criteria information with the given ID. For detailed information, make API call to criteria group path, for example, /criteria/item/{id}.

Authorizations:
path Parameters
id
required
integer <int32>

Responses

200

Successful request with criteria resource in response

Response samples

Content type
application/vnd.adobe.target.v1+json;charset=UTF-8