Skip to main content
Entities are the core content objects in Replyke — 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 replyke.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.
​
location
object
Geographic coordinates { latitude: number; longitude: number }.
​
metadata
object
Arbitrary public metadata.
​
userId
string
The Replyke user ID to set as the entity’s author.
​
createdAt
string
ISO 8601 timestamp to backdate the entity’s creation time.
​
updatedAt
string
ISO 8601 timestamp to backdate the entity’s last update time.
Returns — Promise<Entity>

​
fetchEntity

Fetches a single entity by its Replyke ID. 
const entity = await replyke.entities.fetchEntity({ entityId: "ent_xyz789" });
​
entityId
string
required
The Replyke entity ID.
Returns — Promise<Entity>

​
fetchEntityByForeignId

Fetches an entity by your application’s own identifier. Optionally creates it if not found. 
const entity = await replyke.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.
Returns — Promise<Entity>

​
fetchEntityByShortId

Fetches an entity by its short, human-readable ID (used in share URLs). 
const entity = await replyke.entities.fetchEntityByShortId({ shortId: "abc12" });
​
shortId
string
required
The entity’s short ID.
Returns — Promise<Entity>

​
fetchManyEntities

Fetches a filtered, paginated list of entities. Supports rich filtering by metadata, keywords, location, and more. 
const { data, metadata } = await replyke.entities.fetchManyEntities({
  spaceId: "spc_abc123",
  sortBy: "hot",
  page: 1,
  limit: 20,
  metadataFilters: [{ key: "category", value: "blog", operator: "eq" }],
});
​
sourceId
string
Filter by source ID.
​
spaceId
string
Filter to entities within a specific space.
​
sortBy
string
Sort order: "hot" (trending), "top" (highest scored), or "controversial".
​
page
number
Page number (1-indexed). Defaults to 1.
​
limit
number
Results per page. Defaults to 20.
​
timeFrame
string
Time window for "top" and "controversial" sorts (e.g., "day", "week", "month", "all").
​
userId
string
Filter to entities authored by a specific user.
​
followedOnly
boolean
When true, returns only entities from users the specified userId follows.
​
keywordsFilters
array
Filter entities by keyword tags.
​
metadataFilters
array
Filter entities by metadata fields. Each filter: { key, value, operator }.
​
titleFilters
array
Filter entities by title text.
​
contentFilters
array
Filter entities by content text.
​
mediaFilters
array
Filter by presence or type of media attachments.
​
locationFilters
object
Filter entities within a geographic radius.
Returns — Promise<PaginatedResponse<Entity>>

​
updateEntity

Updates fields on an existing entity. 
const entity = await replyke.entities.updateEntity({
  entityId: "ent_xyz789",
  title: "Updated Title",
  metadata: { featured: true },
});
​
entityId
string
required
The Replyke 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 location { type: "Point"; coordinates: [longitude, latitude] }.
​
metadata
object
Updated metadata. Merged with existing values.
​
mentions
array
Updated user mentions list.
​
createdAt
string
Override the creation timestamp (ISO 8601).
Returns — Promise<Entity>

​
deleteEntity

Permanently deletes an entity and its associated data. 
await replyke.entities.deleteEntity({ entityId: "ent_xyz789" });
​
entityId
string
required
The Replyke 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 replyke.entities.incrementEntityViews({
  entityId: "ent_xyz789",
  count: 1,
});
​
entityId
string
required
The Replyke 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, metadata } = await replyke.entities.fetchDrafts({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
​
userId
string
required
The Replyke user ID whose drafts to fetch.
​
page
number
Page number (1-indexed). Defaults to 1.
​
limit
number
Results per page. Defaults to 20.
Returns — Promise<PaginatedResponse<Entity>>

​
publishDraft

Publishes a draft entity, making it publicly visible. 
const entity = await replyke.entities.publishDraft({ entityId: "ent_xyz789" });
​
entityId
string
required
The Replyke 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 replyke.entities.fetchTopComment({
  entityId: "ent_xyz789",
});
​
entityId
string
required
The Replyke entity ID.
Returns — Promise<TopComment | null>

​
addReaction

Adds a reaction from a user to an entity. 
const reaction = await replyke.entities.addReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
  reactionType: "like",
});
​
entityId
string
required
The Replyke entity ID.
​
userId
string
required
The Replyke 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 replyke.entities.removeReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
​
entityId
string
required
The Replyke entity ID.
​
userId
string
required
The Replyke 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, metadata } = await replyke.entities.fetchReactions({
  entityId: "ent_xyz789",
  reaction: "like",
  page: 1,
  limit: 20,
});
​
entityId
string
required
The Replyke entity ID.
​
reaction
ReactionType
Filter to a specific reaction type.
​
page
number
Page number (1-indexed). Defaults to 1.
​
limit
number
Results per page. Defaults to 20.
Returns — Promise<PaginatedResponse<Reaction>>

​
getUserReaction

Checks what reaction (if any) a specific user has left on an entity. 
const { reactionType } = await replyke.entities.getUserReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
// reactionType is "like" | "upvote" | ... | null
​
entityId
string
required
The Replyke entity ID.
​
userId
string
required
The Replyke 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 replyke.entities.isEntitySaved({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
​
entityId
string
required
The Replyke entity ID.
​
userId
string
required
The Replyke user ID to check.
Returns — Promise<{ isSaved: boolean }>