Fetch Many Entities

Endpoint

URL: https://api.replyke.com/:projectId/entities/

Method: GET

Authentication Required: Optional (Authorization token can be included but is not mandatory)

Description

This endpoint allows fetching multiple entities based on various filters and sorting criteria. It supports optional authentication, meaning it can be accessed with or without an access token. Entities can be filtered by keywords, metadata, content, title, media presence, location, and user-specific preferences (e.g., only fetching posts from followed users). Sorting options include new, top, hot, and controversial, and results can be paginated.

Request

Headers

Authorization: Bearer <accessToken> (Optional, required if fetching user-specific data like followed users’ entities)

URL Parameters

Parameter	Type	Required	Description
`projectId`	`string`	Yes	The project ID associated with the request.

Query Parameters

Parameter	Type	Required	Description
`userId`	`string`	No	Fetch entities created by a specific user.
`sortBy`	`string`	No	Sorting method: `new`, `top`, `hot`, or `controversial`. Default is `hot`.
`page`	`number`	No	The page number for pagination (default: `1`). Must be a whole number >= 1.
`limit`	`number`	No	The number of entities per page (default: `10`).
`timeFrame`	`string`	No	Limits results to entities created within a specific timeframe: `hour`, `day`, `week`, `month`, or `year`.
`keywordsFilters`	`object`	No	Filters entities by keywords using inclusion/exclusion logic. See below for details.
`metadataFilters`	`object`	No	Filters entities based on metadata presence and values. See below for details.
`titleFilters`	`object`	No	Filters entities based on title presence and text matching. See below for details.
`contentFilters`	`object`	No	Filters entities based on content presence and text matching. See below for details.
`mediaFilters`	`object`	No	Filters entities based on whether they contain media. See below for details.
`locationFilters`	`object`	No	Filters entities based on proximity to a given location. See below for details.
`followedOnly`	`boolean`	No	If `true`, returns only entities from followed users (requires authentication).

Example Request URL

GET https://api.replyke.com/:projectId/entities/?sortBy=top&page=1&limit=20&timeFrame=week

Filtering Parameters

`keywordsFilters`

Filters entities based on keywords.

{
  "includes": ["example", "news"],
  "doesNotInclude": ["spam"]
}

includes: The entity must contain at least one of these keywords.
doesNotInclude: The entity must NOT contain any of these keywords.

`metadataFilters`

Filters based on metadata fields.

{
  "includes": {"category": "news"},
  "doesNotInclude": {"category": "spam"},
  "exists": ["author"],
  "doesNotExist": ["deprecated"]
}

includes: The metadata must contain these key-value pairs.
doesNotInclude: The metadata must NOT contain these key-value pairs.
exists: The entity’s metadata must contain these keys.
doesNotExist: The entity’s metadata must NOT contain these keys.

`titleFilters`

Filters entities based on the title field.

{
  "hasTitle": true,
  "includes": ["important", "breaking"],
  "doesNotInclude": ["old"]
}

hasTitle: true means entities must have a title, false means they must not.
includes: The title must contain at least one of these words.
doesNotInclude: The title must NOT contain any of these words.

`contentFilters`

Filters entities based on the content field.

{
  "hasContent": true,
  "includes": ["new feature", "update"],
  "doesNotInclude": ["rumor"]
}

hasContent: true means entities must have content, false means they must not.
includes: The content must contain at least one of these words.
doesNotInclude: The content must NOT contain any of these words.

`mediaFilters`

Filters entities based on whether they contain media.

{
  "hasMedia": true
}

hasMedia: true means entities must have media, false means they must not.

`locationFilters`

Filters entities based on proximity to a given location.

{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "radius": 5000
}

latitude: The latitude of the center point.
longitude: The longitude of the center point.
radius: The search radius in meters.

Response

Success Response (200 OK)

[
  {
    "id": "<ENTITY_ID>",
    "projectId": "<PROJECT_ID>",
    "referenceId": "<REFERENCE_ID>",
    "userId": "<USER_ID>",
    "title": "Entity Title",
    "content": "Entity content...",
    "keywords": ["example", "topic"],
    "mentions": [{ "id": "user-1111", "username": "john_doe" }],
    "location": { "type": "Point", "coordinates": [120.982, 14.604] },
    "upvotes": [],
    "downvotes": [],
    "sharesCount": 0,
    "views": 0,
    "score": 0,
    "metadata": { "category": "news" },
    "createdAt": "<TIMESTAMP>",
    "updatedAt": "<TIMESTAMP>",
    "deletedAt": null
  }
]

Error Responses

Invalid Query Parameter (400 Bad Request)

{
  "error": "Invalid request: 'page' must be a whole number greater than 0"
}

Server Error (500 Internal Server Error)

{
  "error": "Server error"
}

Notes

This endpoint supports advanced filtering using various filters documented above.
Sorting can be done via hot, top, new, or controversial sorting.
If followedOnly is provided, only entities from followed users are returned (if authenticated).

Create Entity Fetch Single Entity