Entities

Create and manage content entities, reactions, and drafts

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.

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.

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

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

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

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<{ 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 }[] }>