Entities

Requires the entities bundle. A project without the entities bundle returns 403 database/tables-not-available for entity calls. See Bundles.

Entities are the central 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" },
});

string

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

string

An optional secondary identifier for grouping or filtering entities.

string

The space this entity belongs to.

string

Title text for the entity.

string

Body/content text for the entity.

array

File or media attachments.

string[]

Tags or keywords used for filtering and discovery.

array

User mentions embedded in the entity.

object

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

object

Arbitrary public metadata.

string

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

boolean

The entity’s own NSFW flag. Defaults to false. Effective NSFW also inherits from the entity’s space. See Entity NSFW flagging.

boolean

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

boolean

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

boolean

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

Date

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

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" });

string

required

The Sublay entity ID.

string

Comma-separated list of associations to populate.

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,
});

string

required

Your application’s entity identifier.

boolean

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

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" });

string

required

The entity’s short ID.

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" } },
});

string

Filter by source ID.

string

Filter to entities within a specific space.

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.

string

Sort direction: "asc" or "desc".

string

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

string

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

number

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

number

Results per page. Defaults to 20.

string

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

string

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

string

The viewing user, used to resolve followedOnly.

"true" | "false"

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

object

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

object

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

object

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

object

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

object

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

object

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

"include-all" | "exclude" | "only"

Filter by effective NSFW (entity.nsfw OR its space's nsfwEffective). "include-all" (default) adds no predicate; "exclude" drops effective-NSFW entities; "only" returns only them. See Entity NSFW flagging.

"exclude" | "include-outbound-blocked"

How to treat entities authored by users the viewer is block-edged with. "exclude" (default) hides them; "include-outbound-blocked" re-includes only the viewer’s own outbound-blocked authors — never content from users who blocked the viewer. No effect without the moderation bundle.

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 },
});

string

required

The Sublay entity ID to update.

string

New title.

string

New content body.

array

Updated attachments list.

string[]

Updated keywords list.

object

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

object

Updated metadata. Merged with existing values.

array

Updated user mentions list.

boolean

Updated NSFW own-flag (owner / service / master). A space moderator flagging another user’s entity uses spaces.setSpaceEntityNsfw instead. See Entity NSFW flagging.

Returns — Promise<Entity>

deleteEntity

Permanently deletes an entity and its associated data.

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

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,
});

string

required

The Sublay entity ID.

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,
});

string

required

The Sublay user ID whose drafts to fetch.

number

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

number

Results per page. Defaults to 20.

string

Filter drafts by source ID.

string

Filter drafts to a specific space.

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" });

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",
});

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",
});

string

required

The Sublay entity ID.

string

required

The Sublay user ID of the reactor.

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",
});

string

required

The Sublay entity ID.

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,
});

string

required

The Sublay entity ID.

ReactionType

Filter to a specific reaction type.

number

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

number

Results per page. Defaults to 20.

string

Sort direction: "asc" or "desc".

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

string

required

The Sublay entity ID.

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",
});

string

required

The Sublay entity ID.

string

required

The Sublay user ID to check.

Returns — Promise<{ isSaved: boolean }>

Getting Started

Modules

createEntity

fetchEntity

fetchEntityByForeignId

fetchEntityByShortId

fetchManyEntities

updateEntity

deleteEntity

incrementEntityViews

fetchDrafts

publishDraft

fetchTopComment

addReaction

removeReaction

fetchReactions

getUserReaction

isEntitySaved

​createEntity

​fetchEntity

​fetchEntityByForeignId

​fetchEntityByShortId

​fetchManyEntities

​updateEntity

​deleteEntity

​incrementEntityViews

​fetchDrafts

​publishDraft

​fetchTopComment

​addReaction

​removeReaction

​fetchReactions

​getUserReaction

​isEntitySaved

createEntity

fetchEntity

fetchEntityByForeignId

fetchEntityByShortId

fetchManyEntities

updateEntity

deleteEntity

incrementEntityViews

fetchDrafts

publishDraft

fetchTopComment

addReaction

removeReaction

fetchReactions

getUserReaction

isEntitySaved