Recommendations API (1.0)

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.

Adobe Target has multiple sets of APIs:

  • Admin API: Programmatically create and modify Activities, Audiences and Offers.
  • Reporting API: Export activity results and other reports.
  • Profile API: Retrieve and modify user profiles stored in Adobe Target.
  • Delivery API: Retrieve optimized and personalized content from Target for delivery and to an end user.

Recommendations API are a subset of the Admin API.

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 legacy Recommendations Classic UI.

  • 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 request payload.
    • Exclusions*
    • Feeds*

    * Coming soon

Authentication

OAuth 2.0

This API uses OAuth 2.0 framework for authentication and authorization. Refer this to the generate access token required for API calls.

Security scheme type: OAuth2
password OAuth Flow
Token URL: https://ims-na1.adobelogin.com/ims/token/
Scopes:

    API Key

    This API also uses API Key for authorization. You can obtain the API Key from your Adobe I/O Console.

    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

    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

    get /collections

    Adobe I/O gateway

    https://mc.adobe.io/adobedemo/target/recs/collections

    Response samples

    application/vnd.adobe.target.v1+json;charset=UTF-8
    Copy
    Expand all Collapse all
    {
    • "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.

    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 object (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

    post /collections

    Adobe I/O gateway

    https://mc.adobe.io/adobedemo/target/recs/collections

    Request samples

    application/vnd.adobe.target.v1+json
    Copy
    Expand all Collapse all
    {
    • "name": "Backpacking Tents",
    • "rules":
      [
      ]
    }

    Response samples

    application/vnd.adobe.target.v1+json;charset=UTF-8
    Copy
    Expand all Collapse all
    {
    • "id": 1,
    • "name": "Backpacking Tents",
    • "rules":
      [
      ]
    }

    Get collection

    Gets the collection with the given ID.

    Authorizations:
    path Parameters
    id
    required
    integer <int32>

    Responses

    200

    Successful request with collection resource in response

    get /collections/{id}

    Adobe I/O gateway

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

    Response samples

    application/vnd.adobe.target.v1+json;charset=UTF-8
    Copy
    Expand all Collapse all
    {
    • "id": 1,
    • "name": "Backpacking Tents",
    • "rules":
      [
      ]
    }

    Edit collection

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

    Authorizations:
    path Parameters
    id
    required
    integer <int32>
    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 object (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

    put /collections/{id}

    Adobe I/O gateway

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

    Request samples

    application/vnd.adobe.target.v1+json
    Copy
    Expand all Collapse all
    {
    • "name": "Backpacking Tents",
    • "rules":
      [
      ]
    }

    Response samples

    application/vnd.adobe.target.v1+json;charset=UTF-8
    Copy
    Expand all Collapse all
    {
    • "id": 1,
    • "name": "Backpacking Tents",
    • "rules":
      [
      ]
    }

    Delete collection

    Deletes the collection referenced by the given ID.

    Authorizations:
    path Parameters
    id
    required
    integer <int32>

    Responses

    200

    Successful request with deleted collection resource in response

    delete /collections/{id}

    Adobe I/O gateway

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

    Response samples

    application/vnd.adobe.target.v1+json;charset=UTF-8
    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

    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

    get /criteria

    Adobe I/O gateway

    https://mc.adobe.io/adobedemo/target/recs/criteria

    Response samples

    application/vnd.adobe.target.v1+json;charset=UTF-8
    Copy
    Expand all Collapse all
    {
    • "offset": "2,",
    • "limit": "2147483647,",
    • "total": 3,
    • "list":
      [