API overview

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:

1. Access the Optimizely Content Recommendations Manager Dashboard
2. Select Deliveries from the navigation menu
3. Open your API delivery configuration
4. 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:

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