Fetch Many Entities
curl --request GET \
--url https://api.sublay.io/v8/:projectId/entities \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.sublay.io/v8/:projectId/entities"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.sublay.io/v8/:projectId/entities', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sublay.io/v8/:projectId/entities",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.sublay.io/v8/:projectId/entities"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.sublay.io/v8/:projectId/entities")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sublay.io/v8/:projectId/entities")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyEntity Endpoints
Fetch Many Entities
Get a paginated, filtered list of entities
Fetch Many Entities
curl --request GET \
--url https://api.sublay.io/v8/:projectId/entities \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.sublay.io/v8/:projectId/entities"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.sublay.io/v8/:projectId/entities', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sublay.io/v8/:projectId/entities",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.sublay.io/v8/:projectId/entities"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.sublay.io/v8/:projectId/entities")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sublay.io/v8/:projectId/entities")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyRequires the
entities bundle. A project without the entities bundle returns 403 database/tables-not-available. See Bundles.Query Parameters
Pagination
number
default:"1"
Page number (1-indexed). A whole number of at least
1 — 0, a negative number or a non-integer value returns 400 entity/invalid-query.number
default:"10"
Number of entities per page. A whole number of at least
1 — 0, a negative number or a non-integer value returns 400 entity/invalid-query. Maximum 100 — larger values are treated as 100.Sorting
string
default:"createdAt"
Sort algorithm. One of:
createdAt— chronological by creation time (honorssortDir; newest first by default)top— by reaction count (usesortByReactionto specify which type)hot— by computed engagement score (decays over time)controversial— high total votes with a close up/down split (entities with no votes sort last)metadata.<property>— sort by a metadata field (e.g.metadata.memberCount)
new is a deprecated alias for createdAt (removed in v8). It still works and
behaves identically, but requests using it receive a non-blocking Deprecation
response header — switch to createdAt.string
default:"DESC"
Sort direction.
ASC or DESC.string
default:"auto"
When using
sortBy=metadata.*, the type of the metadata field. One of auto, numeric, text, boolean, timestamp. auto infers the type at query time.string
default:"upvote"
When
sortBy=top, which reaction type to rank by. One of upvote, downvote, like, love, wow, sad, angry, funny. Only accepted with sortBy=top; sending it with any other sort returns 400 entity/invalid-query.Filtering
string
Restrict to entities created within the last period. One of
hour, day, week, month, year.string
Filter by
sourceId. Pass "null" to return entities with no sourceId.string
Filter by space ID.
string
Filter by the author’s user ID. When this matches the authenticated user’s ID, moderation-removed entities are also included (author can see their own removed posts).
string
When
"true", only returns entities from users the authenticated user follows. Requires authentication.string
default:"exclude"
Controls how entities authored by users the viewer is block-edged with are treated.
"exclude" (default) hides those entities. "include-outbound-blocked" re-includes entities authored only by users the viewer themselves blocked (their own “view anyway” choice); it never surfaces content from users who blocked the viewer. Counts reflect what the viewer sees (computed post-filter). Has no effect when the moderation bundle is not installed.object
Filter by keywords. Pass as a JSON string or bracket-notation query params:
{ "includes": ["react", "typescript"], "doesNotInclude": ["vue"] }
object
Filter by title content:
{
"hasTitle": "true",
"includes": "tutorial",
"doesNotInclude": "beginner"
}
hasTitle:"true"or"false"— filter for presence/absence of a titleincludes: substring(s) to match (case-insensitive)doesNotInclude: substring(s) to exclude
object
Filter by content text. Same structure as
titleFilters (hasContent, includes, doesNotInclude).object
Filter by attachment presence:
{ "hasAttachments": "true" }
object
Filter to entities within a radius of a point:
{ "latitude": "40.7128", "longitude": "-74.0060", "radius": "5000" }
radius is in meters.object
Filter by metadata values. Supports complex conditions:
{
"includes": { "status": "published" },
"includesAny": [{ "type": "video" }, { "type": "image" }],
"doesNotInclude": { "hidden": true },
"exists": ["category"],
"doesNotExist": ["archivedAt"]
}
includes— all key/value pairs must match (AND)includesAny— at least one object must match (OR)doesNotInclude— none of these key/value pairs may matchexists— keys that must be presentdoesNotExist— keys that must be absent
Optional Associations
string
Associations to include in each entity. Pass it as one comma-separated value (
include=user,space) or as repeated params (include=user&include=space). Values:user— the author’s user profilespace— the space the entity belongs totopComments— the entity’s best top-level comments, as full Comment objects (see Top comments)saved— whether the authenticated user has saved this entityfiles— uploaded file/image attachmentsgrants— the reputation-grant summary for the entity
number
default:"1"
With
include=topComments: how many top comments per entity. A whole number of at least 1 — 0, a negative number or a non-integer value returns 400 entity/invalid-query. Maximum 5 — larger values are treated as 5.string
default:"upvote"
With
include=topComments: the reaction whose raw count ranks the top comments (ties newest first). One of upvote, downvote, like, love, wow, sad, angry, funny.include values are case-insensitive. An unknown value returns 400 entity/invalid-query, as does sending topCommentsLimit or topCommentsSortByReaction without include=topComments. topComments lists real content only — deleted, removed and block-edged comments are left out — and is [] when nothing qualifies.
Space-scoped reputation
This endpoint has a space in context, so it accepts the opt-in reputation params. They add aspaceReputation field to each populated author user, alongside the always-present reputation total. Requires the reputation bundle. See the Reputation data model for the full contract.
Response
Returns a paginated response object:{
"data": [ ...Entity[] ],
"pagination": {
"page": 1,
"pageSize": 10,
"totalPages": 5,
"totalItems": 42,
"hasMore": true
}
}
data is an Entity object. File URLs are signed and ready to use.
Viewing scores (
hot sort) are updated asynchronously after each fetch. Scores decay at a rate set per project (feed decay). Entities with equal scores are ordered newest first.Error Responses
Invalid Query — 400
Invalid Query — 400
Returned when
page or limit is below 1 or not a whole number.{ "error": "page: Page must be a positive integer", "code": "entity/invalid-query" }
Invalid include — 400
Invalid include — 400
Returned with code
entity/invalid-query for an unknown include value, when topCommentsLimit is below 1 or not a whole number, or when topCommentsLimit / topCommentsSortByReaction is sent without include=topComments.{ "error": "include: Unknown include `comments`. Allowed: user, space, topComments, saved, files, grants.", "code": "entity/invalid-query" }
Renamed include — 400
Renamed include — 400
include=topComment is rejected with a pointer to its replacement.{
"error": "`include=topComment` was renamed to `topComments` (with `topCommentsLimit` / `topCommentsSortByReaction`).",
"code": "entity/unsupported-param",
"param": "include"
}
See Also
- Reputation data model — the
spaceReputationobject contract - Entity data model

