Entities - Sublay Documentation

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.

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: "new", "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 }.

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

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 }>

​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