Feed Integration - API reference

Overview
Topic Feature & Feed Customization
Personalised Feed API
Universal Feed API

Overview

This document provides a comprehensive reference for integrating and customizing feeds using the LikeMinds platform. It covers topic management, personalized feeds, and universal feeds, including endpoints, parameters, and response formats.

Base URL : https://auth.likeminds.community
All the routes for the api calls will be joined to this url to complete the url path.

Topic Feature & Feed Customization

Overview

The Topic feature allows communities to organize content into thematic groups called "topics". Users can create, edit, delete, and fetch topics. These topics are then used to customize and filter the feed, ensuring users see content relevant to their interests or roles.

API Endpoints

Method	Endpoint	Description
POST	`/feed/topic`	Create one or more topics
GET	`/feed/topic`	Fetch topics
PUT	`/feed/topic/:topic_id`	Edit a topic
DELETE	`/feed/topic`	Delete topics

All endpoints require authentication and appropriate member access.

1. Creating Topics

Endpoint: POST /feed/topic

Request Body

You can create multiple topics at once using either the names array or the topics array for more detailed topic creation.

{
  "names": ["Science", "Technology"],
  "topics": [
    {
      "name": "Mathematics",
      "priority": 1.0,
      "is_searchable": true,
      "parent_id": "",
      "is_enabled": true,
      "metadata": {
        "color": "blue"
      }
    }
  ]
}

Parameters

names (array of strings): Simple topic names to create.
topics (array of objects): Detailed topic creation.
- name (string, required): Name of the topic.
- priority (float, optional): Determines order or importance.
- is_searchable (bool, optional): If true, topic is searchable.
- parent_id (string, optional): For hierarchical topics.
- is_enabled (bool, optional): If false, topic is disabled.
- metadata (object, optional): Custom metadata.

Response

Returns the created topics with their IDs and details.

{
  "success": true,
  "topics": [
    {
      "id": "topic_id_1",
      "name": "Science",
      "priority": 1.0,
      "is_searchable": true,
      "parent_id": "",
      "is_enabled": true,
      "metadata": { "color": "blue" },
      "post_count": 0
    },
    {
      "id": "topic_id_2",
      "name": "Technology",
      "priority": 1.0,
      "is_searchable": true,
      "parent_id": "",
      "is_enabled": true,
      "metadata": {},
      "post_count": 0
    }
  ]
}

2. Fetching Topics

Endpoint: GET /feed/topic

Query Parameters

page (string/int, optional): Pagination page.
page_size (string/int, optional): Number of topics per page.
is_enabled (string/bool, optional): Filter by enabled status.
search_type (string, optional): Type of search (e.g., "name").
search (string, optional): Search term.
min_posts (string/int, optional): Minimum number of posts in topic.
parent_ids (string, optional): Filter by parent topic IDs.
topics_order_by (string, optional): Order topics (e.g., "priority").

Example

GET /feed/topic?page=1&page_size=10&is_enabled=true&search=Science

Response

Returns a paginated list of topics with their details.

{
  "success": true,
  "page": 1,
  "page_size": 2,
  "total": 2,
  "topics": [
    {
      "id": "topic_id_1",
      "name": "Science",
      "priority": 1.0,
      "is_searchable": true,
      "parent_id": "",
      "is_enabled": true,
      "metadata": { "color": "blue" },
      "post_count": 42
    },
    {
      "id": "topic_id_2",
      "name": "Technology",
      "priority": 1.0,
      "is_searchable": true,
      "parent_id": "",
      "is_enabled": true,
      "metadata": {},
      "post_count": 35
    }
  ]
}

3. Editing a Topic

Endpoint: PUT /feed/topic/:topic_id

Request Body

{
  "name": "New Topic Name",
  "is_enabled": true,
  "priority": 2.0,
  "is_searchable": false,
  "metadata": {
    "color": "red"
  }
}

Parameters

name (string, optional): New name.
is_enabled (bool, optional): Enable/disable topic.
priority (float, optional): Update priority.
is_searchable (bool, optional): Update searchability.
metadata (object, optional): Update metadata.

Response

Returns the updated topic details.

{
  "success": true,
  "topic": {
    "id": "topic_id_1",
    "name": "New Topic Name",
    "priority": 2.0,
    "is_searchable": false,
    "parent_id": "",
    "is_enabled": true,
    "metadata": { "color": "red" },
    "post_count": 42
  }
}

4. Deleting Topics

Endpoint: DELETE /feed/topic

Request Body

{
  "topic_ids": ["topic_id_1", "topic_id_2"]
}

Parameters

topic_ids (array of strings, required): IDs of topics to delete.

Response

Returns success/failure for each topic ID.

{
  "success": true,
  "deleted": [
    { "topic_id": "topic_id_1", "status": "deleted" },
    { "topic_id": "topic_id_2", "status": "deleted" }
  ],
  "failed": []
}

5. How Topics Customize the Feed

Feed endpoints (e.g., /feed/personalised, /feed/universal, /feed/group) use topics to filter and organize posts.
When a user selects or follows certain topics, their feed is customized to prioritize posts tagged with those topics.
Topics can be hierarchical, allowing for sub-topics and more granular feed customization.
The backend checks user access and topic status (enabled/disabled) before including topic content in the feed.

Example: Fetching a Personalized Feed

GET /feed/personalised?topics=Science,Technology

Only posts tagged with "Science" or "Technology" topics will be included in the response.

6. Output Example

Topic Object

{
  "id": "topic_id_1",
  "name": "Science",
  "priority": 1.0,
  "is_searchable": true,
  "parent_id": "",
  "is_enabled": true,
  "metadata": {
    "color": "blue"
  },
  "post_count": 42
}

Feed Response (Excerpt)

{
  "feed": [
    {
      "post_id": "post123",
      "content": "Latest in Science...",
      "topics": [
        {
          "id": "topic_id_1",
          "name": "Science"
        }
      ]
    }
  ]
}

7. Access Control

Only users with the correct permissions (e.g., community managers) can create, edit, or delete topics.
All topic-related endpoints check user access before proceeding.

8. Error Handling

Missing or invalid parameters result in a 400 Bad Request with an error message.
Unauthorized access returns a 403 Forbidden.

Personalised Feed API

Endpoint `GET /personalised`

Description

Fetches the personalised feed for the authenticated user. The feed is tailored based on user activity and preferences.

Query Parameters

Name	Type	Default	Description
`page`	integer	1	Page number for pagination.
`page_size`	integer	20	Number of posts per page.
`should_reorder`	boolean	false	If true, reorders the personalised feed (synchronous).
`should_recompute`	boolean	false	If true, triggers a background recomputation of the feed.

Authentication

Requires Bearer token authentication.

Example Request

GET /personalised?page=1&page_size=20&should_reorder=false&should_recompute=false
Authorization: Bearer <token>

Response

200 OK

{
  "success": true,
  "error_message": "",
  "data": {
    "posts": [
      {
        "_id": "string",
        "text": "string",
        "attachments": [
          {
            "file_type": 1,
            "file_url": "string",
            "file_format": "string",
            "file_size": "string"
          }
        ],
        "community_id": "string",
        "is_pinned": false,
        "user_id": "string",
        "likes_count": 0,
        "comments_count": 0,
        "is_saved": false,
        "post_shared_count": 0,
        "menu_items": [
          { "title": "string" }
        ],
        "created_at": 0,
        "updated_at": 0,
        "user": {
          "id": 0,
          "name": "string",
          "image_url": "string",
          "user_unique_id": "string",
          "is_guest": false
        }
      }
    ],
    "users": {
      "user_id": {
        "id": 0,
        "name": "string",
        "image_url": "string",
        "user_unique_id": "string",
        "uuid": "string",
        "sdk_client_info": {
          "community": 0,
          "user": 0,
          "user_unique_id": "string",
          "uuid": "string"
        },
        "is_guest": false,
        "is_deleted": false
      }
    },
    "total_count": 1
  }
}

Notes

If should_reorder is true, the feed is reordered before fetching results.
If should_recompute is true, the feed is recomputed in the background (response is not delayed).
The users object provides metadata for users referenced in the posts.

Universal Feed API

Overview

The Universal Feed API allows an authenticated user to fetch a universal feed of posts. This endpoint is typically used to display a global or community-wide feed. The posts in the universal feed are sorted in reverse cronological order of time of creation.

Endpoint: GET /feed/universal
Authentication: Requires Bearer token (JWT) authentication.

How It Works

Authorization: The API checks the user's identity and access rights.
Parameter Handling: Query parameters are extracted from the request to control pagination and filtering.
Access Check: The user's permission to view posts is validated.
Request Forwarding: The service constructs a request to the backend feed service with the provided parameters and user context.
Response Processing: The response is validated and formatted before being returned to the client.

Query Parameters

Name	Type	Default	Description
`page`	integer	1	Page number for pagination.
`page_size`	integer	20	Number of posts per page.
`topic_ids`	string		(Optional) Comma-separated topic IDs to filter posts.
`widget_ids`	string		(Optional) Comma-separated widget IDs to filter posts.

Note: Only page and page_size are documented in the OpenAPI spec, but the code supports topic_ids and widget_ids as well.
To understand how widgets work refer to this document. An example of widget usage is described here.

Example Request

GET /feed/universal?page=1&page_size=20
Authorization: Bearer <token>

Response

A successful response (200 OK) will have the following structure:

{
  "success": true,
  "error_message": "",
  "data": {
    "posts": [
      {
        "_id": "string",
        "attachments": [
          {
            "file_type": 1,
            "file_url": "string",
            "file_format": "string",
            "file_size": "string"
          }
        ],
        "comments_count": 0,
        "community_id": 0,
        "created_at": 0,
        "is_pinned": false,
        "is_saved": false,
        "post_shared_count": 0,
        "likes_count": 0,
        "menu_items": [
          {
            "title": "string"
          }
        ],
        "text": "string",
        "updated_at": 0,
        "user_id": "string",
        "impressions_count": 0,
        "reach_count": 0
      }
      // ... more posts
    ]
  }
}

Top-level Fields

success (boolean): Indicates if the request was successful.
error_message (string): Error message if the request failed.
data.posts (array): List of post objects.

Post Object Fields

_id: Unique identifier for the post.
attachments: List of attached files (images, videos, etc.).
comments_count: Number of comments on the post.
community_id: ID of the community the post belongs to.
created_at: Timestamp of post creation.
is_pinned: Whether the post is pinned.
is_saved: Whether the post is saved by the user.
post_shared_count: Number of times the post has been shared.
likes_count: Number of likes.
menu_items: List of menu actions available for the post.
text: Content of the post.
updated_at: Timestamp of last update.
user_id: ID of the user who created the post.
impressions_count: Number of times the post was viewed.
reach_count: Number of unique users who saw the post.

Conclusion

This documentation provides a comprehensive guide for integrating and customizing feeds within the LikeMinds platform. The Topic feature enables content organization and personalized user experiences, while the Personalised and Universal Feed APIs offer flexible ways to retrieve and display content based on user preferences and community requirements.

The platform's feed system is designed to be scalable, customizable, and user-friendly, supporting various use cases from simple content discovery to complex community engagement scenarios. Proper implementation of these APIs ensures optimal user experience and efficient content delivery across different community types and sizes.

Feed Integration - API reference

Table of Contents​

Overview​

Topic Feature & Feed Customization​

Overview​

API Endpoints​

1. Creating Topics​

Request Body​

Parameters​

Response​

2. Fetching Topics​

Query Parameters​

Example​

Response​

3. Editing a Topic​

Request Body​

Parameters​

Response​

4. Deleting Topics​

Request Body​

Parameters​

Response​

5. How Topics Customize the Feed​

Example: Fetching a Personalized Feed​

6. Output Example​

Topic Object​

Feed Response (Excerpt)​

7. Access Control​

8. Error Handling​

Personalised Feed API​

Endpoint GET /personalised​

Description​

Query Parameters​

Authentication​

Example Request​

Response​

Notes​

Universal Feed API​

Overview​

How It Works​

Query Parameters​

Example Request​

Response​

Top-level Fields​

Post Object Fields​

Conclusion​

Table of Contents

Overview

Topic Feature & Feed Customization

Overview

API Endpoints

1. Creating Topics

Request Body

Parameters

Response

2. Fetching Topics

Query Parameters

Example

Response

3. Editing a Topic

Request Body

Parameters

Response

4. Deleting Topics

Request Body

Parameters

Response

5. How Topics Customize the Feed

Example: Fetching a Personalized Feed

6. Output Example

Topic Object

Feed Response (Excerpt)

7. Access Control

8. Error Handling

Personalised Feed API

Endpoint `GET /personalised`

Description

Query Parameters

Authentication

Example Request

Response

Notes

Universal Feed API

Overview

How It Works

Query Parameters

Example Request

Response

Top-level Fields

Post Object Fields

Conclusion