API overview

26 min

Introduction

The Optimizely Content Recommendations API provides RESTful endpoints to programmatically manage the core resources that power intelligent content personalization and recommendation systems. Through these endpoints, you can create, read, update, and delete content, users, sections, deliveries, and recommendations to deliver highly targeted, personalized content experiences at scale.

Core capabilities

Content management

Ingest and manage content from multiple sources through URL import

Query and filter content using Lucene search syntax

Update content approval status and featured flags

Retrieve content by ID with full metadata and topic information

Associate content with organizational sections

User management

Create and manage user profiles with custom identifiers

Track user-specific data in structured additional_info fields

Update user information programmatically

Delete users and associated data for privacy compliance

Retrieve personalized content recommendations for individual users

Personalization and recommendations

Fetch personalized content ordered by relevance to specific users

Search within personalized content using Lucene queries

Track recommendation delivery and user interactions

Support for A/B testing with control/test group assignment

Configure recommendation strategies through delivery settings

Configuration management

Manage content delivery configurations (widgets, APIs, feeds)

Define section-based content organization and filtering

Configure recommendation rules and personalization strategies

Multi-tenant architecture with isolated API keys per delivery

API architecture

RESTful design

The API follows REST conventions with:

Resource-based URLs – /content, /users, /recommendations

Standard HTTP Methods – GET, POST, PUT, PATCH, DELETE

JSON Request/Response – Consistent JSON formatting

Stateless Operations – Each request contains all necessary information

Proper HTTP Status Codes – Meaningful status codes for all responses

Core resources

Content (/content)

Content items represent any piece of recommendable content such as articles, blog posts, videos, or products. Each content item includes:

Rich metadata (title, abstract, publication date, custom fields)

Automatic topic extraction and categorization

Source attribution and approval workflows

Image and media asset management

Section associations for organizational grouping

Users (/users)

User profiles capture individual user information and enable personalization:

Flexible user identification (numeric ID or custom identifiers)

Custom data storage in identifiers and additional_info fields

Privacy controls and data management capabilities

Personalized content recommendations based on user behavior

Sections (/sections)

Organizational units for content grouping and targeting:

Define content inclusion rules using Lucene queries

Configure section-specific recommendation strategies

Support for multiple content sources

Performance tracking per section

Deliveries (/deliveries)

Configuration objects that define how and where recommendations are displayed:

Widget delivery configurations

API endpoint customization

Content filtering rules (approval status, featured flags)

Isolated API keys for security

Recommendations (/recommendations/{id})

This resource is update-only — you do not fetch recommendations from it. Personalized content is retrieved from /users/{id}/content (and /users/{id}/recommendations).

Mark a served recommendation as read or pending via PATCH /recommendations/{id}

Record user interaction with a recommendation

Get started

Base URL

All API endpoints use the following URL format:

https://{hostname}/1.0/{resource}

Where {hostname} is your region-specific API endpoint:

api.usea01.idio.episerver.net (US East)

api.emea01.idio.episerver.net (Europe/Middle East/Africa)

api.apac01.idio.episerver.net (Asia-Pacific)

api.caea01.idio.episerver.net (Canada East)

Authentication

The API uses API key authentication passed as a query parameter:

curl "https://api.usea01.idio.episerver.net/1.0/content?key=YOUR_API_KEY"

Obtain API keys

API keys are automatically generated when a delivery is created. To retrieve your API key:

Access the Optimizely Content Recommendations Manager Dashboard

Select Deliveries from the navigation menu

Open your API delivery configuration

Locate and copy the delivery key from the Installation section

Each delivery maintains its own unique API key to ensure security isolation across different integration points.

Request headers

Include these headers in all requests:

Content-Type: application/json
Accept: application/json

Response format

Success responses

Paginated list responses include navigation metadata:

{
  "content": [
    {
      "id": 12345,
      "title": "Example Article",
      "abstract": "Article summary...",
      "published": "2024-01-15T10:30:00Z",
      "original_url": "https://example.com/article",
      ...
    }
  ],
  "total_hits": 150,
  "next_page": "https://api.usea01.idio.episerver.net/1.0/content?page=2&key=...",
  "previous_page": null
}

Single resource responses return the resource object directly:

{
  "id": 12345,
  "title": "Example Article",
  "abstract": "Article summary...",
  "published": "2024-01-15T10:30:00Z",
  ...
}

Confirmation messages return a simple message object:

{
  "message": "Content updated successfully"
}

Error responses

All error responses use a consistent format:

{
  "message": "Detailed error description"
}

HTTP status codes

The API uses standard HTTP status codes:

Code	Status	Description
200	OK	Request completed successfully
201	Created	Resource created successfully
202	Accepted	Request accepted for asynchronous processing
204	No Content	Request successful, no content to return
400	Bad Request	Invalid request parameters or malformed JSON
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions for resource
404	Not Found	Requested resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Pagination

List endpoints support pagination using query parameters:

page – Page number (1-based index)

rpp – Results per page (records per page)

Example:

curl "https://api.usea01.idio.episerver.net/1.0/content?page=2&rpp=20&key=YOUR_API_KEY"

Response includes navigation links:

{
  "content": [...],
  "total_hits": 150,
  "next_page": "https://api.usea01.idio.episerver.net/1.0/content?page=3&rpp=20&key=...",
  "previous_page": "https://api.usea01.idio.episerver.net/1.0/content?page=1&rpp=20&key=..."
}

Common patterns

Create resources

Use POST with a JSON request body:

curl -X POST "https://api.usea01.idio.episerver.net/1.0/users?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": {"customer_id": "12345"},
    "additional_info": {"segment": "premium"}
  }'

Update resources

Most resources use PATCH for partial updates:

curl -X PATCH "https://api.usea01.idio.episerver.net/1.0/content/12345?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"approved": "approved", "featured": true}'

User updates use PUT:

curl -X PUT "https://api.usea01.idio.episerver.net/1.0/users/12345?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": {"customer_id": "12345"},
    "additional_info": {"segment": "premium"}
  }'

Filter and search

Use POST to _filter endpoints with Lucene queries:

curl -X POST "https://api.usea01.idio.episerver.net/1.0/content/_filter?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "title:technology AND published:[2024-01-01 TO *]"}'

Error handling

When errors occur, inspect the HTTP status code and the error message:

{
  "message": "Content does not exist"
}

Common error scenarios

401 Unauthorized – Verify your API key is correct and included in the query string

404 Not Found – Confirm the resource ID exists and you have access to it

400 Bad Request – Check request body format and ensure all required fields are provided

429 Too Many Requests – Implement retry logic with exponential backoff

500 Internal Server Error – Retry the request; contact support if the issue persists

Next steps

Explore the detailed endpoint documentation to learn about specific operations for each resource type:

Content management – Import, search, update, and retrieve content items

User management – Create users and fetch personalized recommendations

Section management – Organize content into logical groupings

Delivery configuration – Manage widget and API delivery settings