> 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 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://docs-beta.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) — Graph UUID
- `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` (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.TaskProgress

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

## 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": {},
    "started_at": "string",
    "status": "string",
    "type": "string",
    "updated_at": "string",
    "uuid": "string"
  }
}
```