> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs-beta.getzep.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-beta.getzep.com/_mcp/server. # Assemble graph context POST https://api.getzep.com/api/v4/graphs/{graph_uuid}/context Content-Type: application/json Reference: https://docs-beta.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) — Graph UUID ### 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. - `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. - `edge_uuids` (list of string, optional) — Include results with any of these edge UUIDs. - `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. - `exclude_node_labels` (list of string, optional) — Exclude results with any of these node labels. - `metadata_filters` (v4.MetadataFilterGroup, optional) — Filter results by episode metadata. - `node_labels` (list of string, optional) — Include results with any of these node labels. - `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. - `target_node_uuids` (list of string, optional) — Include edges that end at any of these node UUIDs. ### 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. - `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 the episode was created. - `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. - `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. - `uuid` (string, optional) — The unique identifier of the episode. - `valid_at` (string, optional) — The time the episode's content became true or was observed, used for temporal reasoning. ### 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. - `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. - `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", "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, "relevance": 1.1, "role": "system", "role_name": "string", "score": 1.1, "selection_rank": 1, "source": "text", "source_description": "string", "thread_uuid": "string", "uuid": "string", "valid_at": "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", "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", "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 } ```