Getting Started

This guide walks you through setting up authentication and making your first API request to the EngageHQ Public Content API.

Prerequisites

Before you begin, you'll need:

1. A JWT Token - Obtained from the ShopHero Identity service
2. Organization Access - Your account must have access to at least one organization
3. HTTP Client - Any tool capable of making HTTP requests (fetch, axios, curl, etc.)

Step 1: Obtain a JWT Token

The EngageHQ API uses JWT tokens issued by the ShopHero Identity service for authentication. Contact your administrator to obtain API credentials.

Token Lifetime

JWT tokens typically expire after 1 hour. Your application should handle token refresh automatically.

Step 2: Make Your First Request

Once you have your token, you can make API requests. Here's a simple example:

// Fetch published content
const response = await fetch(
  'https://cdn.engagehq.retailsuccessplatform.com/api/v1/public/content',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
  }
);

const result = await response.json();

if (result.success) {
  console.log('Content items:', result.data);
  console.log('Total items:', result.meta.total);
} else {
  console.error('Error:', result.message);
}

Step 3: Understand the Response

A successful response looks like this:

{
  "success": true,
  "message": "Content retrieved",
  "data": [
    {
      "id": "con_00000k1L2m3N4o5",
      "type": "article",
      "slug": "summer-sale-announcement",
      "title": "Summer Sale Announcement",
      "description": "Get ready for our biggest summer sale...",
      "tags": ["summer", "sale", "promotions"],
      "metadata": {
        "author": "Marketing Team",
        "reading_time": 5
      },
      "published_at": "2024-06-01T00:00:00Z",
      "is_featured": true
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 1
  }
}

Step 4: Filter and Paginate

Add query parameters to filter and paginate results:

// Get featured articles, page 2
const params = new URLSearchParams({
  type: 'article',
  featured: 'true',
  page: '2',
  per_page: '10',
});

const response = await fetch(
  `https://cdn.engagehq.retailsuccessplatform.com/public/v1/content?${params}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_JWT_TOKEN',
    },
  }
);

Common Errors

Status	Message	Solution
401	Unauthorized	Check your JWT token is valid and not expired
400	Organization context required	Ensure your token includes organization access
404	Content not found	The slug or ID doesn't exist or isn't published

Next Steps

• Authentication - Learn about organization context and token management
• Content API Reference - Full documentation of content endpoints
• Code Examples - Ready-to-use code snippets

Performance Tip

Use the CDN endpoint (cdn.engagehq.retailsuccessplatform.com) for all public content delivery. Content is cached at edge locations worldwide and automatically invalidated when published, giving you the best performance and guaranteed freshness. See Caching Strategy for details.

---

Changelog

Date	Change
2026-03-24	Added custom types and platform elements to content type overview.
2026-02-23	Updated for CloudFront CDN delivery.
2026-02-04	Added section settings and organization requirement.
2026-01-28	Expanded documentation.
2026-01-15	Initial publication.