> 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. # Add edges POST https://api.getzep.com/api/v4/graphs/{graph_uuid}/edges Content-Type: application/json Adds 1 to 100 edges. A name creates a node when deduplicate is false. When deduplicate is true, Zep matches a node by name first. Example: \{"edges":\[\{"fact":"Ada works at Acme Corp","fact\_name":"WORKS\_AT","source\_node":\{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479"},"target\_node":\{"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d480"}},\{"fact":"Ada leads a team","fact\_name":"LEADS","source\_node":\{"name":"Ada Lovelace","labels":\["Person"]},"target\_node":\{"name":"Engineering","labels":\["Department"]}}],"deduplicate":false} Reference: https://docs-beta.getzep.com/sdk-reference/graph/edge/add ## 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.AddEdgesRequest. - `edges` (list of v4.EdgeInput, required) — The edges to add to the graph. The request accepts 1 to 100 edges. - `deduplicate` (boolean, optional) — When true, Zep compares each edge with graph edges and can merge a duplicate or invalidate a contradicted edge. This adds an LLM call per edge. The default is false. ## Response ### 202 Accepted - `edges` (list of v4.AddedEdge, optional) — The accept-time acknowledgements in request order. - `task` (v4.Task, optional) — The asynchronous task that tracks edge creation and indexing. ## 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.EdgeInput - `fact` (string, required) — The fact text describing the relationship between the source and target nodes. - `fact_name` (string, required) — The name of the edge, in upper snake case, for example RELATES_TO. - `source_node` (v4.EdgeNodeRef, required) — The source node. A name creates a node without deduplication, or matches an existing node by name first when deduplication is enabled. - `target_node` (v4.EdgeNodeRef, required) — The target node. A name creates a node without deduplication, or matches an existing node by name first when deduplication is enabled. - `attributes` (map from string to any, optional) — Additional attributes to store on the edge. - `expired_at` (string, optional) — The time at which the fact was superseded or invalidated. - `invalid_at` (string, optional) — The time at which the fact stopped being true. - `metadata` (map from string to any, optional) — Metadata attached to the episode created for this edge. - `valid_at` (string, optional) — The time at which the fact became true. ### v4.AddedEdge - `attributes` (map from string to any, optional) — Additional attributes of the edge. - `expired_at` (string, optional) — The time the fact was superseded or removed. - `fact` (string, optional) — The natural-language fact you submitted for this edge. - `fact_name` (string, optional) — The name of the edge, in upper snake case, for example RELATES_TO. - `invalid_at` (string, optional) — The time at which the fact stopped being true. - `metadata` (map from string to any, optional) — Custom metadata associated with the edge. - `source_node` (v4.EdgeNodeRef, optional) — The source node fields you supplied when creating this edge. - `source_node_uuid` (string, optional) — The source node UUID is set when deduplicate is false. It is the UUID you supplied, or the UUID Zep assigned to a node that the request creates. When deduplicate is true, read the endpoint from the task result. - `target_node` (v4.EdgeNodeRef, optional) — The target node fields you supplied when creating this edge. - `target_node_uuid` (string, optional) — The target node UUID is set when deduplicate is false. It is the UUID you supplied, or the UUID Zep assigned to a node that the request creates. When deduplicate is true, read the endpoint from the task result. - `uuid` (string, optional) — The unique identifier assigned to the edge. - `valid_at` (string, optional) — The time from which the fact is considered true. ### v4.Task - `completed_at` (string, optional) — The time the task reached a terminal status; absent while it is still in progress. - `created_at` (string, optional) — The time the task was created. - `error` (v4.ErrorBody, optional) — The error that caused the task to fail; also present on a partial task when the worker can name a single cause. - `progress` (v4.TaskProgress, optional) — The last processing stage a worker reported for this task. It is not cleared when the task finishes, so a completed task may still show its final stage. - `result` (map from string to any, optional) — Operation-specific output populated once the task reaches succeeded or partial, such as identifiers the operation could not return synchronously. - `started_at` (string, optional) — The time a worker began processing the task; absent until then. - `status` (string, optional) — The task's current state: pending, processing, succeeded, partial, or failed. - `type` (string, optional) — The kind of asynchronous operation the task represents. - `updated_at` (string, optional) — The time the task was last updated. - `uuid` (string, optional) — The unique identifier of the task, used to poll its status. ### v4.ErrorBody - `code` (string, optional) - `details` (map from string to any, optional) - `message` (string, optional) - `param` (string, optional) - `request_id` (string, optional) ### v4.EdgeNodeRef - `attributes` (map from string to any, optional) — Additional attributes of the node, as defined by its entity type. - `labels` (list of string, optional) — The entity type labels to assign to the node. - `name` (string, optional) — The name of the node to create, or to match when deduplication is enabled. - `summary` (string, optional) — A summary of the node. - `uuid` (string, optional) — The unique identifier of an existing node to attach the edge to. ### v4.TaskProgress - `stage` (string, optional) — The most recent processing stage reported by the worker handling the task. ## Examples **Request** ```json { "edges": [ { "fact": "Ada works at Acme Corp", "fact_name": "WORKS_AT", "source_node": {}, "target_node": {} } ] } ``` **Response** ```json { "edges": [ { "attributes": {}, "expired_at": "2024-02-15T10:30:00Z", "fact": "Ada works at Acme Corp", "fact_name": "WORKS_AT", "invalid_at": "2024-02-15T10:30:00Z", "metadata": {}, "source_node": { "attributes": {}, "labels": [ "Organization" ], "name": "Acme Corp", "summary": "A software company", "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "source_node_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "target_node": { "attributes": {}, "labels": [ "Organization" ], "name": "Acme Corp", "summary": "A software company", "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "target_node_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d480", "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "valid_at": "2024-01-15T10:30:00Z" } ], "task": { "completed_at": "string", "created_at": "string", "error": { "code": "string", "details": {}, "message": "string", "param": "string", "request_id": "string" }, "progress": { "stage": "string" }, "result": {}, "started_at": "string", "status": "string", "type": "string", "updated_at": "string", "uuid": "string" } } ```