> This page is for version v4 (default). > For other versions, use one of these documentation indexes: > - v4 (default): https://help.getzep.com/v4/llms.txt > - v3: https://help.getzep.com/v3/llms.txt > - v2: https://help.getzep.com/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://help.getzep.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.getzep.com/_mcp/server. # Assemble graph context POST https://api.getzep.com/api/v4/graphs/{graph_uuid}/context Content-Type: application/json Reference: https://help.getzep.com/sdk-reference/graph/get-context ## Authentication - `Authorization` header (required) (prefixed with ` Api-Key `) — Type "Api-Key" followed by a space and the project API key. ## Request ### Path parameters - `graph_uuid` (string, required) — The UUID of the graph. For a user graph, you can also use the UUID of the user. ### Body (application/json) This endpoint expects a v4.GraphContextRequest. - `query` (string, required) — The search query used to assemble the context block. - `filters` (v4.SearchFilters, optional) — Filters constraining which graph data can be selected for the context block. - `include_results` (boolean, optional) — When true, includes the raw graph results selected for the context block. - `max_characters` (integer, optional) — The maximum number of characters in the assembled context block. - `recency_bias` (enum, optional) — Adjusts result selection to favor more recent graph data. - Allowed values: `off`, `mild`, `strong` - `template_uuid` (string, optional) — The UUID of a context template used to render the context block. ## Response ### 200 OK - `context` (string, optional) — The assembled context block of facts, entities, observations, and thread summaries. Pass it through the model provider's untrusted-data channel. - `results` (v4.ContextResults, optional) — The individual edges, nodes, episodes, observations, and thread summaries selected to build the context. Episodes are always empty because context assembly does not select episodes. Present only when requested. - `truncated` (boolean, optional) — Whether the character budget limited the size of the context block. ## Errors ### 400 Bad Request Error Bad Request - `error` (v4.ErrorBody, optional) ### 401 Unauthorized Error Unauthorized - `error` (v4.ErrorBody, optional) ### 403 Forbidden Error Forbidden - `error` (v4.ErrorBody, optional) ### 404 Not Found Error Not Found - `error` (v4.ErrorBody, optional) ### 409 Conflict Error Conflict - `error` (v4.ErrorBody, optional) ## Types ### v4.SearchFilters - `connected_node_uuids` (list of string, optional) — Include edges connected to any of these node UUIDs. Node search does not support this filter. - `content_policy_violated` (boolean, optional) — Match episodes by their content-policy result. Supported only on episode search when the project setting include_policy_violating_episodes is true. - `date_filters` (v4.DateFilters, optional) — Filter results by temporal values. - `edge_types` (list of string, optional) — Include results with any of these edge types. Node search does not support this filter. - `edge_uuids` (list of string, optional) — Include results with any of these edge UUIDs. Node search does not support this filter. - `episode_uuids` (list of string, optional) — Include results derived from any of these episode UUIDs. - `exclude_edge_types` (list of string, optional) — Exclude results with any of these edge types. Node search does not support this filter. - `exclude_node_labels` (list of string, optional) — Exclude nodes that have any of these labels. On an edge list, the API excludes an edge when its source node or its target node has one of these labels. Edge search does not support this filter. - `metadata_filters` (v4.MetadataFilterGroup, optional) — Filter results by episode metadata. - `node_labels` (list of string, optional) — Include only nodes that have at least one of these labels. On an edge list, the source node and the target node of each edge must each have at least one of these labels. Edge search does not support this filter. - `property_filters` (list of v4.PropertyFilter, optional) — Filter results by node or edge properties. - `source_node_uuids` (list of string, optional) — Include edges that start at any of these node UUIDs. Node search does not support this filter. - `target_node_uuids` (list of string, optional) — Include edges that end at any of these node UUIDs. Node search does not support this filter. ### v4.ContextResults - `edges` (list of v4.ContextEdge, optional) — The edges selected for inclusion in the assembled context. - `episodes` (list of v4.ContextEpisode, optional) — The episodes selected for inclusion in the assembled context. - `nodes` (list of v4.ContextNode, optional) — The nodes selected for inclusion in the assembled context. - `observations` (list of v4.ContextObservation, optional) — The observations selected for inclusion in the assembled context. - `thread_summaries` (list of v4.ContextThreadSummary, optional) — The thread summaries selected for inclusion in the assembled context. ### v4.ErrorBody - `code` (string, optional) - `details` (map from string to any, optional) - `message` (string, optional) - `param` (string, optional) - `request_id` (string, optional) ### v4.DateFilters - `any_of` (list of v4.DateFilterGroup, optional) — Each group is combined with OR logic. ### v4.MetadataFilterGroup - `filters` (list of v4.MetadataFilter, optional) — The metadata predicates in this group. - `groups` (list of v4.MetadataFilterGroup, optional) — The nested metadata groups in this group. - `type` (enum, optional) — The logical operator for this group. - Allowed values: `and`, `or` ### v4.PropertyFilter - `operator` (enum, optional) — The lowercase comparison operator. - Allowed values: `eq`, `ne`, `gt`, `lt`, `gte`, `lte`, `in`, `is_null`, `is_not_null` - `property_name` (string, optional) — The property name to compare. - `value` (V4PropertyFilterValue, optional) — The comparison value. Use an array for in. Its string members must be non-empty, contain no comma, and have no surrounding whitespace. ### v4.ContextEdge - `attributes` (map from string to any, optional) — Additional attributes of the edge. - `created_at` (string, optional) — The time the edge was created. - `episode_uuids` (list of string, optional) — The episodes this edge was derived from. - `expired_at` (string, optional) — The time the fact was superseded or removed. - `fact` (string, optional) — The natural-language fact this edge represents. - `graph_uuid` (string, optional) — The unique identifier of the graph this edge belongs to. - `hyperedge_uuid` (string, optional) — The unique identifier of the hyperedge this edge is a member of. Omitted when the edge is not part of a hyperedge. - `invalid_at` (string, optional) — The time at which the fact stopped being true. - `name` (string, optional) — The name of the edge, in upper snake case, for example RELATES_TO. - `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results. - `scope` (string, optional) — The kind of edge this is, for example entity or episodic. - `score` (double, optional) — The ranking score returned with every search result; omitted when the edge appears in a plain list rather than a search result. - `selection_rank` (integer, optional) — The 1-based position this edge was selected in across all context-assembly scopes. - `source_node_labels` (list of string, optional) — The current labels of the source node. This is read at request time rather than stored on the edge, and is omitted when the source node cannot be resolved. - `source_node_name` (string, optional) — The current name of the source node. This is read at request time rather than stored on the edge, and is omitted when the source node cannot be resolved. - `source_node_uuid` (string, optional) — The unique identifier of the edge's source node. - `target_node_labels` (list of string, optional) — The current labels of the target node. This is read at request time rather than stored on the edge, and is omitted when the target node cannot be resolved. - `target_node_name` (string, optional) — The current name of the target node. This is read at request time rather than stored on the edge, and is omitted when the target node cannot be resolved. - `target_node_uuid` (string, optional) — The unique identifier of the edge's target node. - `user_uuid` (string, optional) — The unique identifier of the user that owns the graph. Present only when the graph is a user graph. - `uuid` (string, optional) — The unique identifier of the edge. - `valid_at` (string, optional) — The time from which the fact is considered true. ### v4.ContextEpisode - `content` (string, optional) — The raw content of the episode. - `content_policy` (v4.EpisodeContentPolicy, optional) — The content policy state of the episode, present only on a graph with a bound content policy rule. - `created_at` (string, optional) — The time Zep received the episode. - `document_id` (string, optional) — The developer-assigned identifier of the document this episode belongs to, present only for episodes added to a document. - `graph_uuid` (string, optional) — The unique identifier of the graph this episode belongs to. - `metadata` (map from string to any, optional) — Custom metadata associated with the episode. - `processed` (boolean, optional) — Whether the episode has finished graph extraction and indexing. - `reference_time` (string, optional) — The episode's reference time, used for temporal reasoning: the time that the developer supplied on add, or the ingestion time when the developer supplied no time. - `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results. - `role` (enum, optional) — The role of the episode's sender, present only when the episode was added as a message. - Allowed values: `system`, `assistant`, `user`, `function`, `tool` - `role_name` (string, optional) — The free-form display name of the episode's sender, present only when the episode was added as a message. - `score` (double, optional) — The ranking score returned with every search result; omitted when the episode appears in a plain list rather than a search result. - `selection_rank` (integer, optional) — The 1-based position this episode was selected in across all context-assembly scopes. - `source` (enum, optional) — The format of the episode's content: text, json, or message. - Allowed values: `text`, `json`, `message`, `fact_triple` - `source_description` (string, optional) — A free-form description of where the episode's content came from. - `thread_uuid` (string, optional) — The thread this episode belongs to, present only for episodes added to a thread. - `user_uuid` (string, optional) — The unique identifier of the user that owns the graph. Present only when the graph is a user graph. - `uuid` (string, optional) — The unique identifier of the episode. ### v4.ContextNode - `episode_uuids` (list of string, required) — The UUIDs of the live episodes that mention this node, newest first. The list is complete when `episode_uuids_truncated` is false. The list holds the newest 100 when the node has more than 100 source episodes; list episodes with the `mentioned_node_uuids` filter to read them all. - `episode_uuids_truncated` (boolean, required) — True when the node has more than 100 source episodes, so `episode_uuids` holds only the newest 100, or when provenance is unavailable. False means `episode_uuids` is the complete set. - `attributes` (map from string to any, optional) — Additional attributes of the node, as defined by its entity type. - `created_at` (string, optional) — The time the node was created. - `degree` (integer, optional) — The count of live entity edges that touch this node, in both directions. Present only when the list request orders by `degree`. - `graph_uuid` (string, optional) — The unique identifier of the graph this node belongs to. - `labels` (list of string, optional) — The entity type labels assigned to the node. - `name` (string, optional) — The name of the entity that the node represents. - `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results. - `score` (double, optional) — The ranking score returned with every search result; omitted when the node appears in a plain list rather than a search result. - `selection_rank` (integer, optional) — The 1-based position this node was selected in across all context-assembly scopes. - `summary` (string, optional) — A generated summary of the entity that the node represents. - `user_uuid` (string, optional) — The unique identifier of the user that owns the graph. Present only when the graph is a user graph. - `uuid` (string, optional) — The node UUID, assigned by Zep. ### v4.ContextObservation - `attributes` (map from string to any, optional) — Additional attributes of the derived node, as defined by its entity type. - `created_at` (string, optional) — The time the observation was created. - `episode_uuids` (list of string, optional) — The unique identifiers of the episodes that support this observation. - `graph_uuid` (string, optional) — The unique identifier of the graph this observation belongs to. - `labels` (list of string, optional) — The labels identifying the type of this observation. - `name` (string, optional) — The name of the observation. - `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results. - `score` (double, optional) — The ranking score returned with every search result; omitted when the observation appears in a plain list rather than a search result. - `selection_rank` (integer, optional) — The 1-based position this observation was selected in across all context-assembly scopes. - `summary` (string, optional) — A generated summary of the observation. - `user_uuid` (string, optional) — The unique identifier of the user that owns the graph. Present only when the graph is a user graph. - `uuid` (string, optional) — The unique identifier of the observation, assigned by Zep. ### v4.ContextThreadSummary - `created_at` (string, optional) — The time the summary was first created. - `last_summarized_at` (string, optional) — The wall-clock time of the most recent summary update. - `last_summarized_episode_valid_at` (string, optional) — The latest episode reference time covered by the most recent summary update. - `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results. - `score` (double, optional) — A score accompanies every search result; it is omitted when the summary appears in a plain list rather than a search result. - `selection_rank` (integer, optional) — The 1-based position this thread summary was selected in across all context-assembly scopes. - `summary` (string, optional) — The generated summary text for the thread. - `thread_uuid` (string, optional) — The unique identifier of the thread this summary belongs to. - `uuid` (string, optional) — The unique identifier of the thread summary. ### v4.DateFilterGroup - `all_of` (list of v4.DateFilter, optional) — All conditions in the group must match. ### v4.MetadataFilter - `operator` (enum, optional) — The lowercase comparison operator. - Allowed values: `eq`, `ne`, `gt`, `lt`, `gte`, `lte`, `in`, `contains`, `is_null`, `is_not_null` - `property_name` (string, optional) — The metadata property name to compare. - `value` (V4MetadataFilterValue, optional) — The comparison value. Use an array for in, a non-empty string for contains, and omit the field for null operators. ### V4PropertyFilterValue The comparison value. Use an array for in. Its string members must be non-empty, contain no comma, and have no surrounding whitespace. ### v4.EpisodeContentPolicy - `category_keys` (list of string, optional) — The keys of the categories with a matched rule. - `dropped_count` (integer, optional) — The number of derived candidates that were dropped. - `retained_count` (integer, optional) — The number of derived candidates that were published to the graph. - `revision` (integer, optional) — The project revision number of the policy the graph bound. - `status` (enum, optional) — The evaluation status. pending means the evaluation has not finished, complete means every candidate was evaluated and the graph batch was written, and failed means ingestion retries were exhausted. - Allowed values: `pending`, `complete`, `failed` - `violated` (boolean, optional) — Whether at least one derived candidate matched a rule. Once true, it stays true. ### v4.DateFilter - `field` (enum, optional) — The temporal field to compare. - Allowed values: `created_at`, `valid_at`, `invalid_at`, `expired_at` - `operator` (enum, optional) — The lowercase comparison operator. - Allowed values: `eq`, `ne`, `gt`, `lt`, `gte`, `lte`, `is_null`, `is_not_null` - `value` (string, optional) — The RFC 3339 timestamp. Omit this field for null operators. ### V4MetadataFilterValue The comparison value. Use an array for in, a non-empty string for contains, and omit the field for null operators. ## Examples **Request** ```json { "query": "string" } ``` **Response** ```json { "context": "string", "results": { "edges": [ { "attributes": {}, "created_at": "string", "episode_uuids": [ "string" ], "expired_at": "string", "fact": "string", "graph_uuid": "string", "hyperedge_uuid": "string", "invalid_at": "string", "name": "string", "relevance": 1.1, "scope": "string", "score": 1.1, "selection_rank": 1, "source_node_labels": [ "string" ], "source_node_name": "string", "source_node_uuid": "string", "target_node_labels": [ "string" ], "target_node_name": "string", "target_node_uuid": "string", "user_uuid": "string", "uuid": "string", "valid_at": "string" } ], "episodes": [ { "content": "string", "content_policy": { "category_keys": [ "health" ], "dropped_count": 0, "retained_count": 7, "revision": 3, "status": "complete", "violated": false }, "created_at": "string", "document_id": "string", "graph_uuid": "string", "metadata": {}, "processed": true, "reference_time": "string", "relevance": 1.1, "role": "system", "role_name": "string", "score": 1.1, "selection_rank": 1, "source": "text", "source_description": "string", "thread_uuid": "string", "user_uuid": "string", "uuid": "string" } ], "nodes": [ { "episode_uuids": [ "string" ], "episode_uuids_truncated": true, "attributes": {}, "created_at": "string", "degree": 1, "graph_uuid": "string", "labels": [ "string" ], "name": "string", "relevance": 1.1, "score": 1.1, "selection_rank": 1, "summary": "string", "user_uuid": "string", "uuid": "string" } ], "observations": [ { "attributes": {}, "created_at": "string", "episode_uuids": [ "string" ], "graph_uuid": "string", "labels": [ "string" ], "name": "string", "relevance": 1.1, "score": 1.1, "selection_rank": 1, "summary": "string", "user_uuid": "string", "uuid": "string" } ], "thread_summaries": [ { "created_at": "string", "last_summarized_at": "string", "last_summarized_episode_valid_at": "string", "relevance": 1.1, "score": 1.1, "selection_rank": 1, "summary": "string", "thread_uuid": "string", "uuid": "string" } ] }, "truncated": true } ```