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 control over their lifecycle, reactions, and drafts. All actions are performed on behalf of the logged-in user.

createEntity

Creates a new entity, optionally as a draft or without attributing it to the logged-in user.

const entity = await sublay.entities.createEntity({
  foreignId: "post-42",
  title: "My First Post",
  content: "Hello world",
  keywords: ["intro", "welcome"],
  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.

Record<string, any>[]

File or media attachments.

string[]

Tags or keywords used for filtering and discovery.

Mention[]

User mentions embedded in the entity.

object

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

Record<string, any>

Arbitrary public metadata.

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.

boolean

When true, creates the entity without attributing it to the logged-in user (authorless).

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.

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 (feeds). 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).

number

Results per page.

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 author to filter by, also used as the viewing user 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?: object; includesAny?: object[]; doesNotInclude?: object; 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.

Record<string, any>[]

Updated attachments list.

string[]

Updated keywords list.

Mention[]

Updated user mentions list.

object

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

Record<string, any>

Updated metadata. Merged with existing values.

boolean

Updated NSFW own-flag. 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>

fetchDrafts

Fetches the logged-in user’s unpublished draft entities.

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

number

Page number (1-indexed).

number

Results per page.

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 the logged-in user’s reaction to an entity and returns the updated entity.

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

string

required

The Sublay entity ID.

ReactionType

required

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

Returns — Promise<Entity>

removeReaction

Removes the logged-in user’s reaction from an entity and returns the updated entity.

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

string

required

The Sublay entity ID.

Returns — Promise<Entity>

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).

number

Results per page.

string

Sort direction: "asc" or "desc".

Returns —

Promise<{ data: Reaction[]; pagination: { page: number; limit: number; total: number; totalPages: number; hasMore: boolean } }>

getUserReaction

Gets the logged-in user’s reaction on an entity. Returns null if there is no reaction.

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

string

required

The Sublay entity ID.

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

isEntitySaved

Checks whether the logged-in user has saved an entity, and in which collections.

const { saved, collections } = await sublay.entities.isEntitySaved({
  entityId: "ent_xyz789",
});

string

required

The Sublay entity ID.

Returns — Promise<{ saved: boolean; collections: { id: string; name: string }[] }>

Getting Started

Modules

createEntity

fetchEntity

fetchEntityByForeignId

fetchEntityByShortId

fetchManyEntities

updateEntity

deleteEntity

fetchDrafts

publishDraft

fetchTopComment

addReaction

removeReaction

fetchReactions

getUserReaction

isEntitySaved

​createEntity

​fetchEntity

​fetchEntityByForeignId

​fetchEntityByShortId

​fetchManyEntities

​updateEntity

​deleteEntity

​fetchDrafts

​publishDraft

​fetchTopComment

​addReaction

​removeReaction

​fetchReactions

​getUserReaction

​isEntitySaved

createEntity

fetchEntity

fetchEntityByForeignId

fetchEntityByShortId

fetchManyEntities

updateEntity

deleteEntity

fetchDrafts

publishDraft

fetchTopComment

addReaction

removeReaction

fetchReactions

getUserReaction

isEntitySaved