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

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

Record<string, any>[]

File or media attachments.

keywords

string[]

Tags or keywords used for filtering and discovery.

mentions

Mention[]

User mentions embedded in the entity.

location

object

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

metadata

Record<string, any>

Arbitrary public metadata.

isDraft

boolean

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

excludeUserId

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

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.

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

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

limit

number

Results per page.

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

Record<string, any>[]

Updated attachments list.

keywords

string[]

Updated keywords list.

mentions

Mention[]

Updated user mentions list.

location

object

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

metadata

Record<string, any>

Updated metadata. Merged with existing values.

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>

fetchDrafts

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

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

page

number

Page number (1-indexed).

limit

number

Results per page.

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

entityId

string

required

The Sublay entity ID.

reactionType

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

entityId

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

entityId

string

required

The Sublay entity ID.

reactionType

ReactionType

Filter to a specific reaction type.

page

number

Page number (1-indexed).

limit

number

Results per page.

sortDir

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

entityId

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

entityId

string

required

The Sublay entity ID.

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

​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