Fetch Entities

Endpoint

URL: /:projectId/entities

Method: GET

Authentication Required: Optional

Fetches a list of entities with full support for pagination, sorting, and advanced filtering. Can be accessed with or without authentication.

Header	Type	Required	Description
`Authorization`	`string`	No	Bearer token to identify the user (optional).

Parameter	Type	Required	Description
`page`	`number`	No	Page number (default: 1).
`limit`	`number`	No	Number of results per page (max: 100).
`sortBy`	`string`	No	Sorting strategy: `hot` (default), `top`, `new`, or `controversial`.
`timeFrame`	`string`	No	Filter by creation time: `hour`, `day`, `week`, `month`, `year`.
`sourceId`	`string`	No	Filter entities by a specific sourceId.
`userId`	`string`	No	Filter by a specific userId.
`followedOnly`	`string`	No	`true` to only show entities by followed users (requires auth).
`keywordsFilters`	`object`	No	Filter entities by keyword inclusion/exclusion.
`metadataFilters`	`object`	No	Filter entities by metadata keys and values.
`titleFilters`	`object`	No	Filter by title presence or matching values.
`contentFilters`	`object`	No	Filter by content presence or matching values.
`attachmentsFilters`	`object`	No	Filter based on whether attachments exist.
`locationFilters`	`object`	No	Filter by location with radius, latitude, and longitude.

GET /proj1234/entities?sortBy=top&limit=10&page=1&followedOnly=true
Authorization: Bearer <ACCESS_TOKEN>

[
  {
    "id": "entity_123",
    "userId": "user_abc",
    "title": "First Post",
    "content": "This is a sample entity.",
    ...
  },
  ...
]

{
  "error": "Invalid request: limit must be a positive number.",
  "code": "entity/invalid-limit"
}

{
  "error": "Invalid request: page must be a whole number greater than 0.",
  "code": "entity/invalid-page"
}

{
  "error": "Internal server error.",
  "code": "entity/server-error",
  "details": "<Error message>"
}

Sort options include:
- hot: Ranked by score (default).
- top: Most upvoted.
- new: Most recent.
- controversial: Balanced upvotes/downvotes.
When followedOnly is true, the response includes only posts by followed users (must be logged in).
Supports complex filters including geospatial queries, keyword matching, content presence, and metadata rules.