Get Posts by Keywords

Retrieve posts filtered by multiple keywords

GET

Retrieve posts that match any of the provided keywords. Supports pagination and returns posts with their associated profile information.

Endpoint:

/api/posts/by-keywords

Query Parameters:

  • keywords - Required. Comma-separated string or array of keywords to search for (e.g., "tech,gadgets" or ["tech", "gadgets"])
  • page (optional) - Page number (default: 1)
  • limit (optional) - Number of items per page (default: 10)

Headers:

Authorization: Bearer YOUR_TOKEN_HERE

Example Request (Comma-separated):

curl -X GET \
  "https://api.getcirclo.com/api/posts/by-keywords?keywords=tech,gadgets&page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Request (Array format):

curl -X GET \
  "https://api.getcirclo.com/api/posts/by-keywords?keywords[]=tech&keywords[]=gadgets&page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response (200 OK):

{
  "posts": [
    {
      "id": "uuid",
      "generatedProfileId": "uuid",
      "postType": "image",
      "caption": "Check out this amazing tech review!",
      "keywords": ["tech", "gadgets", "review"],
      "images": ["https://cdn.example.com/image.jpg"],
      "likeCount": 42,
      "commentCount": 5,
      "createdAt": "2025-11-05T02:20:00Z",
      "updatedAt": "2025-11-05T02:20:00Z",
      "profile": {
        "id": "uuid",
        "name": "John Doe",
        "username": "johndoe",
        "avatar_url": "https://cdn.example.com/avatar.jpg",
        "niche": "Tech Reviewer",
        "sub_niche": "Tech Reviewer"
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 50,
    "itemsPerPage": 10
  }
}

Notes:

  • The endpoint uses JSON_CONTAINS to match posts where any of the provided keywords exist in the post's keywords array.
  • Posts matching any of the provided keywords will be returned (OR logic).
  • Keywords are case-sensitive. Make sure to match the exact format used in posts.
  • If no posts match the keywords, an empty array will be returned with pagination information.

Error Responses:

  • 400: Bad Request - Keywords are required or empty
  • 401: Unauthorized - Missing or invalid token
  • 500: Internal server error