reference.md

Reference

Batch

client.batch.list({ ...params }) -> Zep.BatchListResponse

📝 Description

List batches for the current project, optionally filtered by batch status.

🔌 Usage

await client.batch.list({
    limit: 1,
    cursor: 1,
    status: "status",
});

⚙️ Parameters

request: Zep.BatchListRequest

requestOptions: Batch.RequestOptions

client.batch.create({ ...params }) -> Zep.BatchSummary

📝 Description

Create a draft batch that can be filled with graph episodes and thread messages.

🔌 Usage

await client.batch.create();

⚙️ Parameters

request: Zep.ApidataCreateBatchRequest

requestOptions: Batch.RequestOptions

client.batch.get(batchId) -> Zep.BatchSummary

📝 Description

Get a batch summary, including runtime progress when the batch has been processed.

🔌 Usage

await client.batch.get("batchId");

⚙️ Parameters

batchId: string — The batch ID.

requestOptions: Batch.RequestOptions

client.batch.delete(batchId) -> Zep.SuccessResponse

📝 Description

Delete a draft or invalid unprocessed batch. Processed batches cannot be deleted.

🔌 Usage

await client.batch.delete("batchId");

⚙️ Parameters

batchId: string — The batch ID.

requestOptions: Batch.RequestOptions

client.batch.listItems(batchId, { ...params }) -> Zep.BatchItemListResponse

📝 Description

List items in a batch, including derived runtime status when the batch has been processed.

🔌 Usage

await client.batch.listItems("batchId", {
    limit: 1,
    cursor: 1,
    status: "status",
});

⚙️ Parameters

batchId: string — The batch ID.

request: Zep.BatchListItemsRequest

requestOptions: Batch.RequestOptions

client.batch.add(batchId, { ...params }) -> Zep.BatchItemDetail[]

📝 Description

Add graph episodes and thread messages to a draft batch. Items are appended in request order.

🔌 Usage

await client.batch.add("batchId", {
    items: [
        {
            type: "graph_episode",
        },
    ],
});

⚙️ Parameters

batchId: string — The batch ID.

request: Zep.ApidataAddBatchItemsRequest

requestOptions: Batch.RequestOptions

client.batch.process(batchId) -> Zep.BatchSummary

📝 Description

Start processing a filled batch. Repeated calls return the existing batch run.

🔌 Usage

await client.batch.process("batchId");

⚙️ Parameters

batchId: string — The batch ID.

requestOptions: Batch.RequestOptions

Context

client.context.listContextTemplates() -> Zep.ListContextTemplatesResponse

📝 Description

Lists all context templates.

🔌 Usage

await client.context.listContextTemplates();

⚙️ Parameters

requestOptions: Context.RequestOptions

client.context.createContextTemplate({ ...params }) -> Zep.ContextTemplateResponse

📝 Description

Creates a new context template.

🔌 Usage

await client.context.createContextTemplate({
    template: "template",
    templateId: "template_id",
});

⚙️ Parameters

request: Zep.CreateContextTemplateRequest

requestOptions: Context.RequestOptions

client.context.getContextTemplate(templateId) -> Zep.ContextTemplateResponse

📝 Description

Retrieves a context template by template_id.

🔌 Usage

await client.context.getContextTemplate("template_id");

⚙️ Parameters

templateId: string — Template ID

requestOptions: Context.RequestOptions

client.context.updateContextTemplate(templateId, { ...params }) -> Zep.ContextTemplateResponse

📝 Description

Updates an existing context template by template_id.

🔌 Usage

await client.context.updateContextTemplate("template_id", {
    template: "template",
});

⚙️ Parameters

templateId: string — Template ID

request: Zep.UpdateContextTemplateRequest

requestOptions: Context.RequestOptions

client.context.deleteContextTemplate(templateId) -> Zep.SuccessResponse

📝 Description

Deletes a context template by template_id.

🔌 Usage

await client.context.deleteContextTemplate("template_id");

⚙️ Parameters

templateId: string — Template ID

requestOptions: Context.RequestOptions

Graph

client.graph.listCustomInstructions({ ...params }) -> Zep.ListCustomInstructionsResponse

📝 Description

Lists all custom instructions for a project, user, or graph.

🔌 Usage

await client.graph.listCustomInstructions({
    userId: "user_id",
    graphId: "graph_id",
});

⚙️ Parameters

request: Zep.GraphListCustomInstructionsRequest

requestOptions: Graph.RequestOptions

client.graph.addCustomInstructions({ ...params }) -> Zep.SuccessResponse

📝 Description

Adds new custom instructions for graphs without removing existing ones. If user_ids or graph_ids is empty, adds to project-wide default instructions.

🔌 Usage

await client.graph.addCustomInstructions({
    instructions: [
        {
            name: "name",
            text: "text",
        },
    ],
});

⚙️ Parameters

request: Zep.AddCustomInstructionsRequest

requestOptions: Graph.RequestOptions

client.graph.deleteCustomInstructions({ ...params }) -> Zep.SuccessResponse

📝 Description

Deletes custom instructions for graphs or project wide defaults.

🔌 Usage

await client.graph.deleteCustomInstructions();

⚙️ Parameters

request: Zep.DeleteCustomInstructionsRequest

requestOptions: Graph.RequestOptions

client.graph.listEntityTypes({ ...params }) -> Zep.EntityTypeResponse

📝 Description

Returns all entity types for a project, user, or graph.

🔌 Usage

await client.graph.listEntityTypes({
    userId: "user_id",
    graphId: "graph_id",
});

⚙️ Parameters

request: Zep.GraphListEntityTypesRequest

requestOptions: Graph.RequestOptions

client.graph.setEntityTypesInternal({ ...params }) -> Zep.SuccessResponse

📝 Description

Sets the entity types for multiple users and graphs, replacing any existing ones.

🔌 Usage

await client.graph.setEntityTypesInternal();

⚙️ Parameters

request: Zep.EntityTypeRequest

requestOptions: Graph.RequestOptions

client.graph.add({ ...params }) -> Zep.Episode

📝 Description

Add data to the graph.

🔌 Usage

await client.graph.add({
    data: "data",
    type: "text",
});

⚙️ Parameters

request: Zep.AddDataRequest

requestOptions: Graph.RequestOptions

client.graph.addBatch({ ...params }) -> Zep.Episode[]

📝 Description

Deprecated. Use the Batch API (client.batch.*) instead.

Adds data to the graph in batch mode, processing episodes concurrently.

🔌 Usage

await client.graph.addBatch({
    episodes: [
        {
            data: "data",
            type: "text",
        },
    ],
});

⚙️ Parameters

request: Zep.AddDataBatchRequest

requestOptions: Graph.RequestOptions

client.graph.addFactTriple({ ...params }) -> Zep.AddTripleResponse

📝 Description

Add a fact triple for a user or group

🔌 Usage

await client.graph.addFactTriple({
    fact: "fact",
    factName: "fact_name",
});

⚙️ Parameters

request: Zep.AddTripleRequest

requestOptions: Graph.RequestOptions

client.graph.clone({ ...params }) -> Zep.CloneGraphResponse

📝 Description

Clone a user or group graph.

🔌 Usage

await client.graph.clone();

⚙️ Parameters

request: Zep.CloneGraphRequest

requestOptions: Graph.RequestOptions

client.graph.create({ ...params }) -> Zep.Graph

📝 Description

Creates a new graph.

🔌 Usage

await client.graph.create({
    graphId: "graph_id",
});

⚙️ Parameters

request: Zep.CreateGraphRequest

requestOptions: Graph.RequestOptions

client.graph.listAll({ ...params }) -> Zep.GraphListResponse

📝 Description

Returns all graphs. In order to list users, use user.list_ordered instead

🔌 Usage

await client.graph.listAll({
    pageNumber: 1,
    pageSize: 1,
    search: "search",
    orderBy: "order_by",
    asc: true,
});

⚙️ Parameters

request: Zep.GraphListAllRequest

requestOptions: Graph.RequestOptions

client.graph.detectPatterns({ ...params }) -> Zep.DetectPatternsResponse

📝 Description

Detects structural patterns in a knowledge graph including relationship frequencies, multi-hop paths, co-occurrences, hubs, and clusters. When a query is provided, uses hybrid search to discover seed nodes, detects triple-frequency patterns, and returns resolved edges ranked by relevance.

🔌 Usage

await client.graph.detectPatterns();

⚙️ Parameters

request: Zep.DetectPatternsRequest

requestOptions: Graph.RequestOptions

client.graph.search({ ...params }) -> Zep.GraphSearchResults

📝 Description

Perform a graph search query.

🔌 Usage

await client.graph.search({
    query: "query",
});

⚙️ Parameters

request: Zep.GraphSearchQuery

requestOptions: Graph.RequestOptions

client.graph.get(graphId) -> Zep.Graph

📝 Description

Returns a graph.

🔌 Usage

await client.graph.get("graphId");

⚙️ Parameters

graphId: string — The graph_id of the graph to get.

requestOptions: Graph.RequestOptions

client.graph.delete(graphId) -> Zep.SuccessResponse

📝 Description

Deletes a graph. If you would like to delete a user graph, make sure to use user.delete instead.

🔌 Usage

await client.graph.delete("graphId");

⚙️ Parameters

graphId: string — Graph ID

requestOptions: Graph.RequestOptions

client.graph.update(graphId, { ...params }) -> Zep.Graph

📝 Description

Updates information about a graph.

🔌 Usage

await client.graph.update("graphId");

⚙️ Parameters

graphId: string — Graph ID

request: Zep.UpdateGraphRequest

requestOptions: Graph.RequestOptions

client.graph.warm(graphId) -> Zep.SuccessResponse

📝 Description

Hints Zep to warm a graph for low-latency search

🔌 Usage

await client.graph.warm("graphId");

⚙️ Parameters

graphId: string — The graph_id of the graph to warm.

requestOptions: Graph.RequestOptions

Project

client.project.get() -> Zep.ProjectInfoResponse

📝 Description

Retrieve project info based on the provided api key.

🔌 Usage

await client.project.get();

⚙️ Parameters

requestOptions: Project.RequestOptions

Task

client.task.get(taskId) -> Zep.GetTaskResponse

📝 Description

Gets a task by its ID

🔌 Usage

await client.task.get("task_id");

⚙️ Parameters

taskId: string — Task ID

requestOptions: Task.RequestOptions

Thread

client.thread.listAll({ ...params }) -> Zep.ThreadListResponse

📝 Description

Returns all threads.

🔌 Usage

await client.thread.listAll({
    pageNumber: 1,
    pageSize: 1,
    orderBy: "order_by",
    asc: true,
});

⚙️ Parameters

request: Zep.ThreadListAllRequest

requestOptions: Thread.RequestOptions

client.thread.create({ ...params }) -> Zep.Thread

📝 Description

Start a new thread.

🔌 Usage

await client.thread.create({
    threadId: "thread_id",
    userId: "user_id",
});

⚙️ Parameters

request: Zep.CreateThreadRequest

requestOptions: Thread.RequestOptions

client.thread.delete(threadId) -> Zep.SuccessResponse

📝 Description

Deletes a thread.

🔌 Usage

await client.thread.delete("threadId");

⚙️ Parameters

threadId: string — The ID of the thread for which memory should be deleted.

requestOptions: Thread.RequestOptions

client.thread.getUserContext(threadId, { ...params }) -> Zep.ThreadContextResponse

📝 Description

Returns most relevant context from the user graph (including memory from any/all past threads) based on the content of the past few messages of the given thread.

🔌 Usage

await client.thread.getUserContext("threadId", {
    templateId: "template_id",
});

⚙️ Parameters

threadId: string — The ID of the current thread (for which context is being retrieved).

request: Zep.ThreadGetUserContextRequest

requestOptions: Thread.RequestOptions

client.thread.get(threadId, { ...params }) -> Zep.MessageListResponse

📝 Description

Returns messages for a thread.

🔌 Usage

await client.thread.get("threadId", {
    limit: 1,
    cursor: 1000000,
    lastn: 1,
});

⚙️ Parameters

threadId: string — Thread ID

request: Zep.ThreadGetRequest

requestOptions: Thread.RequestOptions

client.thread.addMessages(threadId, { ...params }) -> Zep.AddThreadMessagesResponse

📝 Description

Add messages to a thread.

🔌 Usage

await client.thread.addMessages("threadId", {
    messages: [
        {
            content: "content",
            role: "norole",
        },
    ],
});

⚙️ Parameters

threadId: string — The ID of the thread to which messages should be added.

request: Zep.AddThreadMessagesRequest

requestOptions: Thread.RequestOptions

client.thread.addMessagesBatch(threadId, { ...params }) -> Zep.AddThreadMessagesResponse

📝 Description

Deprecated. Use the Batch API (client.batch.* with type: "thread_message") instead.

Adds messages to a thread in batch mode, processing messages concurrently.

🔌 Usage

await client.thread.addMessagesBatch("threadId", {
    messages: [
        {
            content: "content",
            role: "norole",
        },
    ],
});

⚙️ Parameters

threadId: string — The ID of the thread to which messages should be added.

request: Zep.AddThreadMessagesRequest

requestOptions: Thread.RequestOptions

client.thread.getSummary(threadId) -> Zep.ThreadSummary

📝 Description

Returns the incremental summary generated from messages in the thread. Returns 404 if no summary exists for the thread.

🔌 Usage

await client.thread.getSummary("threadId");

⚙️ Parameters

threadId: string — The thread ID.

requestOptions: Thread.RequestOptions

User

client.user.listUserSummaryInstructions({ ...params }) -> Zep.ListUserInstructionsResponse

📝 Description

Lists all user summary instructions for a project, user.

🔌 Usage

await client.user.listUserSummaryInstructions({
    userId: "user_id",
});

⚙️ Parameters

request: Zep.UserListUserSummaryInstructionsRequest

requestOptions: User.RequestOptions

client.user.addUserSummaryInstructions({ ...params }) -> Zep.SuccessResponse

📝 Description

Adds new summary instructions for users graphs without removing existing ones. If user_ids is empty, adds to project-wide default instructions.

🔌 Usage

await client.user.addUserSummaryInstructions({
    instructions: [
        {
            name: "name",
            text: "text",
        },
    ],
});

⚙️ Parameters

request: Zep.AddUserInstructionsRequest

requestOptions: User.RequestOptions

client.user.deleteUserSummaryInstructions({ ...params }) -> Zep.SuccessResponse

📝 Description

Deletes user summary/instructions for users or project wide defaults.

🔌 Usage

await client.user.deleteUserSummaryInstructions();

⚙️ Parameters

request: Zep.DeleteUserInstructionsRequest

requestOptions: User.RequestOptions

client.user.add({ ...params }) -> Zep.User

📝 Description

Adds a user.

🔌 Usage

await client.user.add({
    userId: "user_id",
});

⚙️ Parameters

request: Zep.CreateUserRequest

requestOptions: User.RequestOptions

client.user.listOrdered({ ...params }) -> Zep.UserListResponse

📝 Description

Returns all users.

🔌 Usage

await client.user.listOrdered({
    pageNumber: 1,
    pageSize: 1,
    search: "search",
    orderBy: "order_by",
    asc: true,
});

⚙️ Parameters

request: Zep.UserListOrderedRequest

requestOptions: User.RequestOptions

client.user.get(userId) -> Zep.User

📝 Description

Returns a user.

🔌 Usage

await client.user.get("userId");

⚙️ Parameters

userId: string — The user_id of the user to get.

requestOptions: User.RequestOptions

client.user.delete(userId) -> Zep.SuccessResponse

📝 Description

Deletes a user.

🔌 Usage

await client.user.delete("userId");

⚙️ Parameters

userId: string — User ID

requestOptions: User.RequestOptions

client.user.update(userId, { ...params }) -> Zep.User

📝 Description

Updates a user.

🔌 Usage

await client.user.update("userId");

⚙️ Parameters

userId: string — User ID

request: Zep.UpdateUserRequest

requestOptions: User.RequestOptions

client.user.getNode(userId) -> Zep.UserNodeResponse

📝 Description

Returns a user's node.

🔌 Usage

await client.user.getNode("userId");

⚙️ Parameters

userId: string — The user_id of the user to get the node for.

requestOptions: User.RequestOptions

client.user.getThreads(userId) -> Zep.Thread[]

📝 Description

Returns all threads for a user.

🔌 Usage

await client.user.getThreads("userId");

⚙️ Parameters

userId: string — User ID

requestOptions: User.RequestOptions

client.user.warm(userId) -> Zep.SuccessResponse

📝 Description

Hints Zep to warm a user's graph for low-latency search

🔌 Usage

await client.user.warm("userId");

⚙️ Parameters

userId: string — User ID

requestOptions: User.RequestOptions

Graph Edge

client.graph.edge.getByGraphId(graphId, { ...params }) -> Zep.EntityEdge[]

📝 Description

Returns all edges for a graph.

🔌 Usage

await client.graph.edge.getByGraphId("graph_id", {});

⚙️ Parameters

graphId: string — Graph ID

request: Zep.GraphEdgesRequest

requestOptions: Edge.RequestOptions

client.graph.edge.getByUserId(userId, { ...params }) -> Zep.EntityEdge[]

📝 Description

Returns all edges for a user.

🔌 Usage

await client.graph.edge.getByUserId("user_id", {});

⚙️ Parameters

userId: string — User ID

request: Zep.GraphEdgesRequest

requestOptions: Edge.RequestOptions

client.graph.edge.get(uuid) -> Zep.EntityEdge

📝 Description

Returns a specific edge by its UUID.

🔌 Usage

await client.graph.edge.get("uuid");

⚙️ Parameters

uuid: string — Edge UUID

requestOptions: Edge.RequestOptions

client.graph.edge.delete(uuid) -> Zep.SuccessResponse

📝 Description

Deletes an edge by UUID.

🔌 Usage

await client.graph.edge.delete("uuid");

⚙️ Parameters

uuid: string — Edge UUID

requestOptions: Edge.RequestOptions

client.graph.edge.update(uuid, { ...params }) -> Zep.EntityEdge

📝 Description

Updates an entity edge by UUID.

🔌 Usage

await client.graph.edge.update("uuid");

⚙️ Parameters

uuid: string — Edge UUID

request: Zep.graph.UpdateEdgeRequest

requestOptions: Edge.RequestOptions

Graph Episode

client.graph.episode.getByGraphId(graphId, { ...params }) -> Zep.EpisodeResponse

📝 Description

Returns episodes by graph id.

🔌 Usage

await client.graph.episode.getByGraphId("graph_id", {
    lastn: 1,
});

⚙️ Parameters

graphId: string — Graph ID

request: Zep.graph.EpisodeGetByGraphIdRequest

requestOptions: Episode.RequestOptions

client.graph.episode.getByUserId(userId, { ...params }) -> Zep.EpisodeResponse

📝 Description

Returns episodes by user id.

🔌 Usage

await client.graph.episode.getByUserId("user_id", {
    lastn: 1,
});

⚙️ Parameters

userId: string — User ID

request: Zep.graph.EpisodeGetByUserIdRequest

requestOptions: Episode.RequestOptions

client.graph.episode.get(uuid) -> Zep.Episode

📝 Description

Returns episodes by UUID

🔌 Usage

await client.graph.episode.get("uuid");

⚙️ Parameters

uuid: string — Episode UUID

requestOptions: Episode.RequestOptions

client.graph.episode.delete(uuid) -> Zep.SuccessResponse

📝 Description

Deletes an episode by its UUID.

🔌 Usage

await client.graph.episode.delete("uuid");

⚙️ Parameters

uuid: string — Episode UUID

requestOptions: Episode.RequestOptions

client.graph.episode.update(uuid, { ...params }) -> Zep.Episode

📝 Description

Update episode metadata with merge semantics. Supplied keys overwrite or add to existing metadata; keys set to null are removed.

🔌 Usage

await client.graph.episode.update("uuid", {
    metadata: {
        key: "value",
    },
});

⚙️ Parameters

uuid: string — Episode UUID

request: Zep.graph.UpdateEpisodeRequest

requestOptions: Episode.RequestOptions

client.graph.episode.getNodesAndEdges(uuid) -> Zep.EpisodeMentions

📝 Description

Returns nodes and edges mentioned in an episode

🔌 Usage

await client.graph.episode.getNodesAndEdges("uuid");

⚙️ Parameters

uuid: string — Episode uuid

requestOptions: Episode.RequestOptions

Graph Node

client.graph.node.getByGraphId(graphId, { ...params }) -> Zep.EntityNode[]

📝 Description

Returns all nodes for a graph.

🔌 Usage

await client.graph.node.getByGraphId("graph_id", {});

⚙️ Parameters

graphId: string — Graph ID

request: Zep.GraphNodesRequest

requestOptions: Node.RequestOptions

client.graph.node.getByUserId(userId, { ...params }) -> Zep.EntityNode[]

📝 Description

Returns all nodes for a user

🔌 Usage

await client.graph.node.getByUserId("user_id", {});

⚙️ Parameters

userId: string — User ID

request: Zep.GraphNodesRequest

requestOptions: Node.RequestOptions

client.graph.node.getEdges(nodeUuid) -> Zep.EntityEdge[]

📝 Description

Returns all edges for a node

🔌 Usage

await client.graph.node.getEdges("node_uuid");

⚙️ Parameters

nodeUuid: string — Node UUID

requestOptions: Node.RequestOptions

client.graph.node.getEpisodes(nodeUuid) -> Zep.EpisodeResponse

📝 Description

Returns all episodes that mentioned a given node

🔌 Usage

await client.graph.node.getEpisodes("node_uuid");

⚙️ Parameters

nodeUuid: string — Node UUID

requestOptions: Node.RequestOptions

client.graph.node.get(uuid) -> Zep.EntityNode

📝 Description

Returns a specific node by its UUID.

🔌 Usage

await client.graph.node.get("uuid");

⚙️ Parameters

uuid: string — Node UUID

requestOptions: Node.RequestOptions

client.graph.node.delete(uuid) -> Zep.SuccessResponse

📝 Description

Deletes a node by UUID.

🔌 Usage

await client.graph.node.delete("uuid");

⚙️ Parameters

uuid: string — Node UUID

requestOptions: Node.RequestOptions

client.graph.node.update(uuid, { ...params }) -> Zep.EntityNode

📝 Description

Updates an entity node by UUID.

🔌 Usage

await client.graph.node.update("uuid");

⚙️ Parameters

uuid: string — Node UUID

request: Zep.graph.UpdateNodeRequest

requestOptions: Node.RequestOptions

Graph Observation

client.graph.observation.getByGraphId(graphId, { ...params }) -> Zep.DerivedNode[]

📝 Description

Returns read-only observation nodes for a graph.

🔌 Usage

await client.graph.observation.getByGraphId("graph_id", {});

⚙️ Parameters

graphId: string — Graph ID

request: Zep.GraphObservationsRequest

requestOptions: Observation.RequestOptions

client.graph.observation.getByUserId(userId, { ...params }) -> Zep.DerivedNode[]

📝 Description

Returns read-only observation nodes for a user's graph.

🔌 Usage

await client.graph.observation.getByUserId("user_id", {});

⚙️ Parameters

userId: string — User ID

request: Zep.GraphObservationsRequest

requestOptions: Observation.RequestOptions

client.graph.observation.get(uuid) -> Zep.DerivedNode

📝 Description

Returns a specific observation node by UUID. Observation nodes are read-only.

🔌 Usage

await client.graph.observation.get("uuid");

⚙️ Parameters

uuid: string — Observation UUID

requestOptions: Observation.RequestOptions

Graph ThreadSummary

client.graph.threadSummary.getByGraphId(graphId, { ...params }) -> Zep.ThreadSummary[]

📝 Description

Returns incremental thread summaries associated with the graph.

🔌 Usage

await client.graph.threadSummary.getByGraphId("graph_id", {});

⚙️ Parameters

graphId: string — Graph ID

request: Zep.GraphThreadSummariesRequest

requestOptions: ThreadSummary.RequestOptions

client.graph.threadSummary.getByUserId(userId, { ...params }) -> Zep.ThreadSummary[]

📝 Description

Returns incremental thread summaries generated from messages in each thread associated with the user's graph.

🔌 Usage

await client.graph.threadSummary.getByUserId("user_id", {});

⚙️ Parameters

userId: string — User ID

request: Zep.GraphThreadSummariesRequest

requestOptions: ThreadSummary.RequestOptions

Thread Message

client.thread.message.update(messageUuid, { ...params }) -> Zep.Message

📝 Description

Updates a message.

🔌 Usage

await client.thread.message.update("messageUUID", {
    metadata: {
        key: "value",
    },
});

⚙️ Parameters

messageUuid: string — The UUID of the message.

request: Zep.thread.ThreadMessageUpdate

requestOptions: Message.RequestOptions