> 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.

# Add hyperedge member

POST https://api.getzep.com/api/v4/graphs/{graph_uuid}/hyperedges/{hyperedge_uuid}/edges
Content-Type: application/json

Adds one member edge to an existing hyperedge. The new member inherits the
hyperedge's fact and timestamps and joins its episodes, so only its own
name and node pair are supplied.

Reference: https://help.getzep.com/sdk-reference/graph/hyperedge/create-edge

## 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.
- `hyperedge_uuid` (string, required) — Hyperedge UUID

### Body (application/json)

This endpoint expects a v4.AddHyperedgeEdgeRequest.

- `name` (string, required) — The name of the new member edge, in upper snake case.
- `source_node` (v4.EdgeNodeRef, required) — The source node of the new member.
- `target_node` (v4.EdgeNodeRef, required) — The target node of the new member.

## Response

### 202

Accepted

- `edge` (v4.AddedEdge, optional) — An accept-time acknowledgement of the member edge, carrying the identifier Zep assigned and the hyperedge's shared fields.
- `task` (v4.Task, optional) — The asynchronous task that tracks writing the member edge.

## 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)

## Types

### 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.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` (v4.TaskResult, 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` (enum, optional) — The task's current state: pending, processing, succeeded, partial, or failed.
  - Allowed values: `pending`, `processing`, `succeeded`, `partial`, `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.TaskProgress

- `stage` (string, optional) — The most recent processing stage reported by the worker handling the task.

### v4.TaskResult

- `content_policy` (v4.TaskResultContentPolicy, optional) — The content policy outcome of the task.
- `edge_uuid` (string, optional) — The UUID of the edge that the task wrote.
- `edges` (list of v4.TaskResultEdge, optional) — The edges that the task wrote.
- `episode_uuid` (string, optional) — The UUID of the episode that the task added.
- `episodes` (list of v4.TaskResultEpisode, optional) — The content policy outcome of each message that the task added.
- `hyperedge_uuid` (string, optional) — The UUID of the hyperedge that the task created.
- `skill_uuid` (string, optional) — The UUID of the skill that the task imported.
- `source_node_uuid` (string, optional) — The UUID of the source node of the edge that the task wrote.
- `target_node_uuid` (string, optional) — The UUID of the target node of the edge that the task wrote.

### v4.TaskResultContentPolicy

- `category_keys` (list of string, optional) — The keys of the categories with a matched rule.
- `dropped_count` (integer, optional) — The number of derived candidates of the episode that were dropped.
- `failed_count` (integer, optional) — The number of episodes in the batch whose evaluation failed.
- `retained_count` (integer, optional) — The number of derived candidates of the episode that were published to the graph.
- `revision` (integer, optional) — The project revision number of the policy that the graph bound.
- `status` (enum, optional) — The evaluation status of the episode. pending means the evaluation has not finished, complete means every candidate was evaluated, and failed means ingestion retries were exhausted.
  - Allowed values: `pending`, `complete`, `failed`
- `violated` (boolean, optional) — Whether at least one derived candidate of the episode matched a rule.
- `violated_count` (integer, optional) — The number of episodes in the batch that a content policy flagged.

### v4.TaskResultEdge

- `edge_uuid` (string, optional) — The UUID of the edge.
- `source_node_uuid` (string, optional) — The UUID of the source node of the edge.
- `target_node_uuid` (string, optional) — The UUID of the target node of the edge.

### v4.TaskResultEpisode

- `content_policy` (v4.TaskResultContentPolicy, optional) — The content policy state of the episode.
- `episode_uuid` (string, optional) — The UUID of the episode of the message.

## Examples

**Request**

```json
{
  "name": "string",
  "source_node": {},
  "target_node": {}
}
```

**Response**

```json
{
  "edge": {
    "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": {
      "content_policy": {
        "category_keys": [
          "health"
        ],
        "dropped_count": 0,
        "failed_count": 1,
        "retained_count": 7,
        "revision": 3,
        "status": "complete",
        "violated": false,
        "violated_count": 2
      },
      "edge_uuid": "7a1f3c2e-4b5d-4e6f-8a9b-0c1d2e3f4a5b",
      "edges": [
        {
          "edge_uuid": "7a1f3c2e-4b5d-4e6f-8a9b-0c1d2e3f4a5b",
          "source_node_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
          "target_node_uuid": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f"
        }
      ],
      "episode_uuid": "f6a7b8c9-d0e1-4f2a-9b4c-5d6e7f8091a2",
      "episodes": [
        {
          "content_policy": {
            "category_keys": [
              "health"
            ],
            "dropped_count": 0,
            "failed_count": 1,
            "retained_count": 7,
            "revision": 3,
            "status": "complete",
            "violated": false,
            "violated_count": 2
          },
          "episode_uuid": "f6a7b8c9-d0e1-4f2a-9b4c-5d6e7f8091a2"
        }
      ],
      "hyperedge_uuid": "d4e5f6a7-b8c9-4d0e-9f2a-3b4c5d6e7f80",
      "skill_uuid": "e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8091",
      "source_node_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "target_node_uuid": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f"
    },
    "started_at": "string",
    "status": "pending",
    "type": "string",
    "updated_at": "string",
    "uuid": "string"
  }
}
```