> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replyke.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entities

> Create and manage content entities, reactions, drafts, and view counts from your server

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.

```typescript theme={null}
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" },
});
```

<ParamField body="foreignId" type="string">
  Your application's identifier for this entity. Used for idempotent lookups via `fetchEntityByForeignId`.
</ParamField>

<ParamField body="sourceId" type="string">
  An optional secondary identifier for grouping or filtering entities.
</ParamField>

<ParamField body="spaceId" type="string">
  The space this entity belongs to.
</ParamField>

<ParamField body="title" type="string">
  Title text for the entity.
</ParamField>

<ParamField body="content" type="string">
  Body/content text for the entity.
</ParamField>

<ParamField body="attachments" type="array">
  File or media attachments.
</ParamField>

<ParamField body="keywords" type="string[]">
  Tags or keywords used for filtering and discovery.
</ParamField>

<ParamField body="location" type="object">
  Geographic coordinates `{ latitude: number; longitude: number }`.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary public metadata.
</ParamField>

<ParamField body="userId" type="string">
  The Replyke user ID to set as the entity's author.
</ParamField>

<ParamField body="createdAt" type="string">
  ISO 8601 timestamp to backdate the entity's creation time.
</ParamField>

<ParamField body="updatedAt" type="string">
  ISO 8601 timestamp to backdate the entity's last update time.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchEntity

Fetches a single entity by its Replyke ID.

```typescript theme={null}
const entity = await replyke.entities.fetchEntity({ entityId: "ent_xyz789" });
```

<ParamField body="entityId" type="string" required>
  The Replyke entity ID.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchEntityByForeignId

Fetches an entity by your application's own identifier. Optionally creates it if not found.

```typescript theme={null}
const entity = await replyke.entities.fetchEntityByForeignId({
  foreignId: "post-42",
  createIfNotFound: true,
});
```

<ParamField body="foreignId" type="string" required>
  Your application's entity identifier.
</ParamField>

<ParamField body="createIfNotFound" type="boolean">
  When `true`, creates a stub entity if no match is found. Defaults to `false`.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchEntityByShortId

Fetches an entity by its short, human-readable ID (used in share URLs).

```typescript theme={null}
const entity = await replyke.entities.fetchEntityByShortId({ shortId: "abc12" });
```

<ParamField body="shortId" type="string" required>
  The entity's short ID.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchManyEntities

Fetches a filtered, paginated list of entities. Supports rich filtering by metadata, keywords, location, and more.

```typescript theme={null}
const { data, metadata } = await replyke.entities.fetchManyEntities({
  spaceId: "spc_abc123",
  sortBy: "hot",
  page: 1,
  limit: 20,
  metadataFilters: [{ key: "category", value: "blog", operator: "eq" }],
});
```

<ParamField body="sourceId" type="string">
  Filter by source ID.
</ParamField>

<ParamField body="spaceId" type="string">
  Filter to entities within a specific space.
</ParamField>

<ParamField body="sortBy" type="string">
  Sort order: `"hot"` (trending), `"top"` (highest scored), or `"controversial"`.
</ParamField>

<ParamField body="page" type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField body="limit" type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField body="timeFrame" type="string">
  Time window for `"top"` and `"controversial"` sorts (e.g., `"day"`, `"week"`, `"month"`, `"all"`).
</ParamField>

<ParamField body="userId" type="string">
  Filter to entities authored by a specific user.
</ParamField>

<ParamField body="followedOnly" type="boolean">
  When `true`, returns only entities from users the specified `userId` follows.
</ParamField>

<ParamField body="keywordsFilters" type="array">
  Filter entities by keyword tags.
</ParamField>

<ParamField body="metadataFilters" type="array">
  Filter entities by metadata fields. Each filter: `{ key, value, operator }`.
</ParamField>

<ParamField body="titleFilters" type="array">
  Filter entities by title text.
</ParamField>

<ParamField body="contentFilters" type="array">
  Filter entities by content text.
</ParamField>

<ParamField body="mediaFilters" type="array">
  Filter by presence or type of media attachments.
</ParamField>

<ParamField body="locationFilters" type="object">
  Filter entities within a geographic radius.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Entity>>`

***

### updateEntity

Updates fields on an existing entity.

```typescript theme={null}
const entity = await replyke.entities.updateEntity({
  entityId: "ent_xyz789",
  title: "Updated Title",
  metadata: { featured: true },
});
```

<ParamField body="entityId" type="string" required>
  The Replyke entity ID to update.
</ParamField>

<ParamField body="title" type="string">
  New title.
</ParamField>

<ParamField body="content" type="string">
  New content body.
</ParamField>

<ParamField body="attachments" type="array">
  Updated attachments list.
</ParamField>

<ParamField body="keywords" type="string[]">
  Updated keywords list.
</ParamField>

<ParamField body="location" type="object">
  Updated location `{ type: "Point"; coordinates: [longitude, latitude] }`.
</ParamField>

<ParamField body="metadata" type="object">
  Updated metadata. Merged with existing values.
</ParamField>

<ParamField body="mentions" type="array">
  Updated user mentions list.
</ParamField>

<ParamField body="createdAt" type="string">
  Override the creation timestamp (ISO 8601).
</ParamField>

**Returns** — `Promise<Entity>`

***

### deleteEntity

Permanently deletes an entity and its associated data.

```typescript theme={null}
await replyke.entities.deleteEntity({ entityId: "ent_xyz789" });
```

<ParamField body="entityId" type="string" required>
  The Replyke entity ID to delete.
</ParamField>

**Returns** — `Promise<void>`

***

### incrementEntityViews

Increments the view counter on an entity. Call this when a user views content to track engagement.

```typescript theme={null}
const entity = await replyke.entities.incrementEntityViews({
  entityId: "ent_xyz789",
  count: 1,
});
```

<ParamField body="entityId" type="string" required>
  The Replyke entity ID.
</ParamField>

<ParamField body="count" type="number">
  Number to add to the view counter. Defaults to `1`.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchDrafts

Fetches a user's unpublished draft entities.

```typescript theme={null}
const { data, metadata } = await replyke.entities.fetchDrafts({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField body="userId" type="string" required>
  The Replyke user ID whose drafts to fetch.
</ParamField>

<ParamField body="page" type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField body="limit" type="number">
  Results per page. Defaults to `20`.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Entity>>`

***

### publishDraft

Publishes a draft entity, making it publicly visible.

```typescript theme={null}
const entity = await replyke.entities.publishDraft({ entityId: "ent_xyz789" });
```

<ParamField body="entityId" type="string" required>
  The Replyke entity ID of the draft to publish.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchTopComment

Fetches the highest-scored (top) comment on an entity. Returns `null` if the entity has no comments.

```typescript theme={null}
const topComment = await replyke.entities.fetchTopComment({
  entityId: "ent_xyz789",
});
```

<ParamField body="entityId" type="string" required>
  The Replyke entity ID.
</ParamField>

**Returns** — `Promise<TopComment | null>`

***

### addReaction

Adds a reaction from a user to an entity.

```typescript theme={null}
const reaction = await replyke.entities.addReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
  reactionType: "like",
});
```

<ParamField body="entityId" type="string" required>
  The Replyke entity ID.
</ParamField>

<ParamField body="userId" type="string" required>
  The Replyke user ID of the reactor.
</ParamField>

<ParamField body="reactionType" type="ReactionType" required>
  One of: `"upvote"`, `"downvote"`, `"like"`, `"love"`, `"wow"`, `"sad"`, `"angry"`, `"funny"`.
</ParamField>

**Returns** — `Promise<Reaction>`

***

### removeReaction

Removes a user's existing reaction from an entity.

```typescript theme={null}
await replyke.entities.removeReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
```

<ParamField body="entityId" type="string" required>
  The Replyke entity ID.
</ParamField>

<ParamField body="userId" type="string" required>
  The Replyke user ID whose reaction to remove.
</ParamField>

**Returns** — `Promise<void>`

***

### fetchReactions

Fetches a paginated list of reactions on an entity, optionally filtered by reaction type.

```typescript theme={null}
const { data, metadata } = await replyke.entities.fetchReactions({
  entityId: "ent_xyz789",
  reaction: "like",
  page: 1,
  limit: 20,
});
```

<ParamField body="entityId" type="string" required>
  The Replyke entity ID.
</ParamField>

<ParamField body="reaction" type="ReactionType">
  Filter to a specific reaction type.
</ParamField>

<ParamField body="page" type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField body="limit" type="number">
  Results per page. Defaults to `20`.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Reaction>>`

***

### getUserReaction

Checks what reaction (if any) a specific user has left on an entity.

```typescript theme={null}
const { reactionType } = await replyke.entities.getUserReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
// reactionType is "like" | "upvote" | ... | null
```

<ParamField body="entityId" type="string" required>
  The Replyke entity ID.
</ParamField>

<ParamField body="userId" type="string" required>
  The Replyke user ID to check.
</ParamField>

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

***

### isEntitySaved

Checks whether a user has saved an entity to any of their collections.

```typescript theme={null}
const { isSaved } = await replyke.entities.isEntitySaved({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
```

<ParamField body="entityId" type="string" required>
  The Replyke entity ID.
</ParamField>

<ParamField body="userId" type="string" required>
  The Replyke user ID to check.
</ParamField>

**Returns** — `Promise<{ isSaved: boolean }>`