Contents API

The Contents API is used for populating and managing content items in Discovery OS content indexes. This API enables you to create, update, and delete content entries that can be searched using the Content Search API.

Content items are stored in named indexes (aliases) and can contain any custom data structure. Each content item is identified by a unique identifier (refId).

IMPORTANT

• At least one content item is required per API call.
• A maximum of 1000 content items are allowed per API call.
• Content items are indexed into the specified alias (content index).
• The contentData field accepts any valid JSON object structure.

API Endpoints

Create Contents

Method: POST

URL: https://<PA_END_POINT>/contents/index/{alias}

Update Contents

Method: PUT

URL: https://<PA_END_POINT>/contents/index/{alias}

Delete Contents

Method: DELETE

URL: https://<PA_END_POINT>/contents/index/{alias}

Path Parameters

Parameter	Type	Required	Description
alias	string	✅	The content index alias name to operate on.

Request Header

Name	Value
Content-Type	application/json
Authorization	Bearer ACCESS_TOKEN

Request Parameters (Body)

contents (array) [REQUIRED]

Parameter	Type	Required	Description
refId	string	✅	A unique identifier for the content item. Maximum length 255 characters.
contentData	object	✅	A JSON object containing the content data. Can include any custom fields.

Example Request Payload

{
    "contents": [
        {
            "refId": "article-001",
            "contentData": {
                "title": "Getting Started with Discovery OS",
                "category": "Documentation",
                "author": "PA Team",
                "publishDate": "2024-03-15",
                "tags": ["getting-started", "tutorial", "basics"],
                "summary": "Learn how to integrate Discovery OS into your platform.",
                "content": "This comprehensive guide walks you through the initial setup...",
                "readTime": 10,
                "featured": true
            }
        },
        {
            "refId": "article-002",
            "contentData": {
                "title": "Advanced Search Configuration",
                "category": "Documentation",
                "author": "PA Team",
                "publishDate": "2024-03-20",
                "tags": ["search", "configuration", "advanced"],
                "summary": "Deep dive into search configuration options.",
                "content": "This article covers advanced search configuration techniques...",
                "readTime": 15,
                "featured": false
            }
        },
        {
            "refId": "faq-001",
            "contentData": {
                "question": "How do I reset my API credentials?",
                "answer": "Navigate to Settings > API Keys and click 'Regenerate'.",
                "category": "FAQ",
                "helpful_count": 42
            }
        }
    ]
}

Response Payload

On successful operation, the returned status code will be 202, and the payload will contain the status message "Accepted" and a transaction ID.

{
    "transactionId": "xxxxxxxxxxxxxxxxxxxxxxx",
    "status": "Accepted"
}

For bulk operations, the request may be partially accepted. In that case the response will be:

{
    "transactionId": "xxxxxxxxxxxxxxxxxxxxxxx",
    "status": "PartiallyAccepted",
    "message": "Number of Invalid Records: 2",
    "validationMessages": [
        "contents[0]: Content must contain a RefId",
        "contents[5]: RefId length should not be greater than 255"
    ]
}

Error Response

If there are any errors, the response status code will not be 202, and the relevant error messages will be provided as part of "errors" in the returned message. Here is an example:

{
    "errors": {
        "Contents": [
            "Contents array must not be null or empty"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "xxxxxxxxxxxxxxxxxxx"
}

Example Usage (JavaScript)

Creating Contents

// Replace <PA_END_POINT> with your actual API endpoint
const alias = 'articles'; // Your content index alias
const apiUrl = `https://<PA_END_POINT>/contents/index/${alias}`;
// Replace this with your actual access token
const accessToken = 'YOUR_ACCESS_TOKEN';

const headers = {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`
};

const body = JSON.stringify({
    contents: [
        {
            refId: "article-001",
            contentData: {
                title: "Getting Started with Discovery OS",
                category: "Documentation",
                author: "PA Team",
                publishDate: "2024-03-15",
                tags: ["getting-started", "tutorial", "basics"],
                summary: "Learn how to integrate Discovery OS into your platform.",
                readTime: 10,
                featured: true
            }
        }
        // Add more content items as needed
    ]
});

fetch(apiUrl, {
    method: 'POST',
    headers: headers,
    body: body
})
.then(response => response.json())
.then(data => console.log('API response:', data))
.catch(error => console.error('Error creating contents:', error));

Updating Contents

const alias = 'articles';
const apiUrl = `https://<PA_END_POINT>/contents/index/${alias}`;
const accessToken = 'YOUR_ACCESS_TOKEN';

const headers = {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`
};

const body = JSON.stringify({
    contents: [
        {
            refId: "article-001",
            contentData: {
                title: "Getting Started with Discovery OS - Updated",
                category: "Documentation",
                author: "PA Team",
                publishDate: "2024-03-15",
                tags: ["getting-started", "tutorial", "basics", "updated"],
                summary: "Updated guide for integrating Discovery OS.",
                readTime: 12,
                featured: true
            }
        }
    ]
});

fetch(apiUrl, {
    method: 'PUT',
    headers: headers,
    body: body
})
.then(response => response.json())
.then(data => console.log('API response:', data))
.catch(error => console.error('Error updating contents:', error));

Deleting Contents

const alias = 'articles';
const apiUrl = `https://<PA_END_POINT>/contents/index/${alias}`;
const accessToken = 'YOUR_ACCESS_TOKEN';

const headers = {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`
};

const body = JSON.stringify({
    contents: [
        { refId: "article-001" },
        { refId: "article-002" }
    ]
});

fetch(apiUrl, {
    method: 'DELETE',
    headers: headers,
    body: body
})
.then(response => response.json())
.then(data => console.log('API response:', data))
.catch(error => console.error('Error deleting contents:', error));

Summary

This document provides information about the Contents API, including its purpose, methods, URLs, request body parameters, example payloads, and returned payloads.

• The API allows creation, update, and deletion of content entries within named content indexes (aliases).
• Each content item requires a unique refId and a contentData object containing the actual content.
• The contentData field is flexible and can contain any valid JSON structure to suit your content needs.
• Bulk operations are supported with up to 1000 content items per request.
• Content items can be searched using the Content Search API after ingestion.