Entities

Create and manage content entities, reactions, drafts, and view counts from your server

Entities are the core content objects in Sublay — posts, articles, products, or any item in your application that users interact with. The entities module gives you full server-side control over their lifecycle.

---

createEntity

Creates a new entity.

const entity = await sublay.entities.createEntity({
  foreignId: "post-42",
  title: "My First Post",
  content: "Hello world",
  keywords: ["intro", "welcome"],
  userId: "usr_abc123",
  metadata: { category: "blog" },
});

foreignId · string

Your application’s identifier for this entity. Used for idempotent lookups via fetchEntityByForeignId.

sourceId · string

An optional secondary identifier for grouping or filtering entities.

spaceId · string

The space this entity belongs to.

title · string

Title text for the entity.

content · string

Body/content text for the entity.

attachments · array

File or media attachments.

keywords · string[]

Tags or keywords used for filtering and discovery.

mentions · array

User mentions embedded in the entity.

location · object

Geographic coordinates { latitude: number; longitude: number }.

metadata · object

Arbitrary public metadata.

userId · string

The Sublay user ID to set as the entity’s author.

isDraft · boolean

When true, the entity is created as an unpublished draft. Defaults to false.

excludeUserId · boolean

When true, creates the entity with no author association even if userId is provided.

requireUser · boolean

When true, the request fails unless a valid author user is resolved.

createdAt · Date

A Date used to backdate the entity’s creation time.

updatedAt · Date

A Date used to backdate the entity’s last update time.

Returns — Promise<Entity>

---

fetchEntity

Fetches a single entity by its Sublay ID.

const entity = await sublay.entities.fetchEntity({ entityId: "ent_xyz789" });

entityId · string · required

The Sublay entity ID.

include · string

Comma-separated list of associations to populate.

spaceReputationId · string

Opts the returned entity’s author into a spaceReputation number. Accepts a space <uuid>, "none" (the project-general bucket), or "context" (the space derived from the request context). The empty string and the legacy general / null aliases are rejected. See Reputation.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<Entity>

---

fetchEntityByForeignId

Fetches an entity by your application’s own identifier. Optionally creates it if not found.

const entity = await sublay.entities.fetchEntityByForeignId({
  foreignId: "post-42",
  createIfNotFound: true,
});

foreignId · string · required

Your application’s entity identifier.

createIfNotFound · boolean

When true, creates a stub entity if no match is found. Defaults to false.

include · string

Comma-separated list of associations to populate.

Returns — Promise<Entity>

---

fetchEntityByShortId

Fetches an entity by its short, human-readable ID (used in share URLs).

const entity = await sublay.entities.fetchEntityByShortId({ shortId: "abc12" });

shortId · string · required

The entity’s short ID.

include · string

Comma-separated list of associations to populate.

Returns — Promise<Entity>

---

fetchManyEntities

Fetches a filtered, paginated list of entities. Supports rich filtering by metadata, keywords, location, and more.

const { data, pagination } = await sublay.entities.fetchManyEntities({
  spaceId: "spc_abc123",
  sortBy: "hot",
  page: 1,
  limit: 20,
  metadataFilters: { includes: { category: "blog" } },
});

sourceId · string

Filter by source ID.

spaceId · string

Filter to entities within a specific space.

sortBy · string

Sort order: "createdAt" (chronological — honors sortDir), "hot" (trending), "top" (highest scored), or "controversial". A "metadata.<prop>" value is also accepted to sort by a metadata field.

sortDir · string

Sort direction: "asc" or "desc".

sortType · string

How to interpret a metadata sort value: "auto", "numeric", "text", "boolean", or "timestamp".

sortByReaction · string

Sort by the count of a specific reaction: "upvote", "downvote", "like", "love", "wow", "sad", "angry", or "funny".

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

include · string

Comma-separated list of associations to populate (e.g. "user").

timeFrame · string

Time window to restrict results to: "hour", "day", "week", "month", or "year".

userId · string

The viewing user, used to resolve followedOnly.

followedOnly · "true" | "false"

When "true", returns only entities from users the given userId follows.

keywordsFilters · object

Filter by keyword tags: { includes?: string[]; doesNotInclude?: string[] }.

metadataFilters · object

Filter by metadata fields: { includes?, includesAny?, doesNotInclude?, exists?: string[], doesNotExist?: string[] }.

titleFilters · object

Filter by title: { hasTitle?: "true" | "false"; includes?: string | string[]; doesNotInclude?: string | string[] }.

contentFilters · object

Filter by content: { hasContent?: "true" | "false"; includes?: string | string[]; doesNotInclude?: string | string[] }.

attachmentsFilters · object

Filter by attachments: { hasAttachments?: "true" | "false" }.

locationFilters · object

Filter within a geographic radius: { latitude: string; longitude: string; radius: string }.

spaceReputationId · string

Opts each returned entity’s author into a spaceReputation number. Accepts a space <uuid>, "none" (the project-general bucket), or "context" (the space derived from the request context — resolved per-row from the space each entity belongs to). The empty string and the legacy general / null aliases are rejected. See Reputation.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<PaginatedResponse<Entity>>

---

updateEntity

Updates fields on an existing entity.

const entity = await sublay.entities.updateEntity({
  entityId: "ent_xyz789",
  title: "Updated Title",
  metadata: { featured: true },
});

entityId · string · required

The Sublay entity ID to update.

title · string

New title.

content · string

New content body.

attachments · array

Updated attachments list.

keywords · string[]

Updated keywords list.

location · object

Updated coordinates { latitude: number; longitude: number }.

metadata · object

Updated metadata. Merged with existing values.

mentions · array

Updated user mentions list.

Returns — Promise<Entity>

---

deleteEntity

Permanently deletes an entity and its associated data.

await sublay.entities.deleteEntity({ entityId: "ent_xyz789" });

entityId · string · required

The Sublay entity ID to delete.

Returns — Promise<void>

---

incrementEntityViews

Increments the view counter on an entity. Call this when a user views content to track engagement.

const entity = await sublay.entities.incrementEntityViews({
  entityId: "ent_xyz789",
  count: 1,
});

entityId · string · required

The Sublay entity ID.

count · number

Number to add to the view counter. Defaults to 1.

Returns — Promise<Entity>

---

fetchDrafts

Fetches a user’s unpublished draft entities.

const { data, pagination } = await sublay.entities.fetchDrafts({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});

userId · string · required

The Sublay user ID whose drafts to fetch.

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

sourceId · string

Filter drafts by source ID.

spaceId · string

Filter drafts to a specific space.

include · string

Comma-separated list of associations to populate.

Returns — Promise<PaginatedResponse<Entity>>

---

publishDraft

Publishes a draft entity, making it publicly visible.

const entity = await sublay.entities.publishDraft({ entityId: "ent_xyz789" });

entityId · string · required

The Sublay entity ID of the draft to publish.

Returns — Promise<Entity>

---

fetchTopComment

Fetches the highest-scored (top) comment on an entity. Returns null if the entity has no comments.

const topComment = await sublay.entities.fetchTopComment({
  entityId: "ent_xyz789",
});

entityId · string · required

The Sublay entity ID.

Returns — Promise<TopComment | null>

---

addReaction

Adds a reaction from a user to an entity.

const reaction = await sublay.entities.addReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
  reactionType: "like",
});

entityId · string · required

The Sublay entity ID.

userId · string · required

The Sublay user ID of the reactor.

reactionType · ReactionType · required

One of: "upvote", "downvote", "like", "love", "wow", "sad", "angry", "funny".

Returns — Promise<Reaction>

---

removeReaction

Removes a user’s existing reaction from an entity.

await sublay.entities.removeReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});

entityId · string · required

The Sublay entity ID.

userId · string · required

The Sublay user ID whose reaction to remove.

Returns — Promise<void>

---

fetchReactions

Fetches a paginated list of reactions on an entity, optionally filtered by reaction type.

const { data, pagination } = await sublay.entities.fetchReactions({
  entityId: "ent_xyz789",
  reactionType: "like",
  page: 1,
  limit: 20,
});

entityId · string · required

The Sublay entity ID.

reactionType · ReactionType

Filter to a specific reaction type.

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

sortDir · string

Sort direction: "asc" or "desc".

spaceReputationId · string

Opts each returned reactor into a spaceReputation number. Accepts a space <uuid>, "none" (the project-general bucket), or "context" (the space derived from the request context). The empty string and the legacy general / null aliases are rejected. See Reputation.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<PaginatedResponse<Reaction>>

---

getUserReaction

Checks what reaction (if any) a specific user has left on an entity.

const { reactionType } = await sublay.entities.getUserReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
// reactionType is "like" | "upvote" | ... | null

entityId · string · required

The Sublay entity ID.

userId · string · required

The Sublay user ID to check.

Returns — Promise<{ reactionType: ReactionType | null }>

---

isEntitySaved

Checks whether a user has saved an entity to any of their collections.

const { isSaved } = await sublay.entities.isEntitySaved({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});

entityId · string · required

The Sublay entity ID.

userId · string · required

The Sublay user ID to check.

Returns — Promise<{ isSaved: boolean }>