Edges API

Edges are typed, weighted connections between snapshots. They transform your collection of isolated ideas into a knowledge graph — revealing how your thinking supports itself, where contradictions hide, and how ideas evolved over time.

Every edge has a type (what kind of relationship), a strength (how strong the connection is, 0–1), and an optional label (a human-readable description). Edges power the Brain Graph visualization and influence search ranking.

Automatic edge creation

When you crystallize text, NeuralSnap automatically detects relationships between the resulting snapshots and any existing snapshots in your brain. You can also create edges manually for connections only you can see.

Edge Types

NeuralSnap supports six edge types. Choosing the right type makes your graph more meaningful and improves search relevance.

supports

The source snapshot provides evidence or backing for the target.

"Compound interest is powerful" → supports → "Start investing early"

contradicts

The source challenges or conflicts with the target.

"Move fast and break things" → contradicts → "Measure twice, cut once"

elaborates

The source expands on or adds detail to the target.

"How to run a sprint planning" → elaborates → "Agile works for small teams"

caused_by

The source was caused by or originated from the target.

"I now batch all meetings on Tuesdays" → caused_by → "Context switching kills deep work"

evolved_from

The source is a newer version or evolution of the target.

"Ship MVPs, then iterate" → evolved_from → "Plan everything before building"

related_to

General relationship — the ideas are connected but not in a specific directional way.

"Writing clarifies thinking" → related_to → "Teaching is the best way to learn"

List Edges

Retrieve edges for a specific snapshot or an entire brain. Use filters to narrow results by edge type or minimum connection strength.

GET/edges

List edges for a snapshot or brain.

Query Parameters

Property	Type	Description
`snapshot_id`	string	Get edges connected to a specific snapshot. Returns both incoming and outgoing edges.
`brain_id`	string	Get all edges in a brain. Use for graph visualization.
`edge_type`	enum	Filter by type: supports, contradicts, elaborates, caused_by, evolved_from, related_to.
`min_strength`	number	Minimum connection strength (0–1). Default: 0. Use 0.7+ for strong connections only.
`limit`	number	Max results to return. Default: 50, max: 200.
`offset`	number	Pagination offset. Default: 0.

At least one filter required

You must provide either snapshot_id or brain_id. If both are provided, snapshot_id takes precedence.

bash

# Get all edges for a snapshot
curl "https://api.neuralsnap.ai/v1/edges?snapshot_id=snap_a1b2c3d4e5f6" \
  -H "Authorization: Bearer ns_test_abc123"

# Get only contradictions, strong connections
curl "https://api.neuralsnap.ai/v1/edges?brain_id=brain_abc123&edge_type=contradicts&min_strength=0.7" \
  -H "Authorization: Bearer ns_test_abc123"

json

{
  "data": [
    {
      "id": "edge_x1y2z3",
      "brain_id": "brain_abc123",
      "source_id": "snap_a1b2c3d4e5f6",
      "target_id": "snap_g7h8i9j0k1l2",
      "edge_type": "supports",
      "strength": 0.85,
      "label": "Practical evidence for compound growth",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 1
}

Create Edge

Manually create a connection between two snapshots. This is useful when you spot a relationship that the automatic edge detection missed, or when you want to explicitly mark a contradiction or evolution in your thinking.

POST/edges

Create a typed connection between two snapshots.

Request Body

Property	Type	Description
`source_id`*	string	UUID of the source snapshot (the 'from' side of the relationship).
`target_id`*	string	UUID of the target snapshot (the 'to' side of the relationship).
`edge_type`*	enum	Relationship type: supports, contradicts, elaborates, caused_by, evolved_from, related_to.
`strength`	number	Connection strength from 0 to 1. Default: 0.5. Higher values surface more prominently in the graph.
`label`	string	Human-readable description of why these snapshots are connected.

bash

curl -X POST https://api.neuralsnap.ai/v1/edges \
  -H "Authorization: Bearer ns_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
  "source_id": "snap_a1b2c3d4e5f6",
  "target_id": "snap_g7h8i9j0k1l2",
  "edge_type": "supports",
  "strength": 0.85,
  "label": "First principles thinking directly supports the build-from-scratch approach"
}'

json

{
  "data": {
    "id": "edge_x1y2z3",
    "brain_id": "brain_abc123",
    "source_id": "snap_a1b2c3d4e5f6",
    "target_id": "snap_g7h8i9j0k1l2",
    "edge_type": "supports",
    "strength": 0.85,
    "label": "First principles thinking directly supports the build-from-scratch approach",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
  }
}

Duplicate edges

You cannot create two edges of the same type between the same pair of snapshots. If you need to update the strength or label, use the update endpoint instead.

Update Edge

Update an edge's strength, type, or label. Useful when your understanding of a relationship changes — for example, you realize two ideas don't just relate, they actually contradict each other.

PUT/edges/:id

Update an existing edge.

Request Body

Property	Type	Description
`edge_type`	enum	New relationship type.
`strength`	number	New connection strength (0–1).
`label`	string	New description.

bash

curl -X PUT https://api.neuralsnap.ai/v1/edges/edge_x1y2z3 \
  -H "Authorization: Bearer ns_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
  "edge_type": "contradicts",
  "strength": 0.9,
  "label": "Actually, these ideas are in tension"
}'

json

{
  "data": {
    "id": "edge_x1y2z3",
    "brain_id": "brain_abc123",
    "source_id": "snap_a1b2c3d4e5f6",
    "target_id": "snap_g7h8i9j0k1l2",
    "edge_type": "contradicts",
    "strength": 0.9,
    "label": "Actually, these ideas are in tension",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-16T14:20:00.000Z"
  }
}

Delete Edge

Remove a connection between snapshots. The snapshots themselves are not affected.

DELETE/edges/:id

Remove a connection between snapshots.

bash

curl -X DELETE https://api.neuralsnap.ai/v1/edges/edge_x1y2z3 \
  -H "Authorization: Bearer ns_test_abc123"

json

{
  "message": "Edge deleted successfully"
}

Common Use Cases

🔍 Find contradictions in your thinking

Query all contradicts edges in your brain to surface ideas that are in tension. This is powerful for decision-making — if you hold two contradictory beliefs, one of them needs updating.

GET /edges?brain_id=...&edge_type=contradicts&min_strength=0.5

🌱 Track how your thinking evolved

Use evolved_from edges to see how an idea changed over time. Chain them together to build a timeline of intellectual growth.

GET /edges?snapshot_id=...&edge_type=evolved_from

🕸️ Build the full graph for visualization

Fetch all edges in a brain to render a force-directed graph. Use strength values for edge thickness and edge types for coloring.

GET /edges?brain_id=...&limit=200

Error Handling

Property	Type	Description
`400`	Bad Request	Missing required fields (source_id, target_id, edge_type) or invalid edge_type value.
`401`	Unauthorized	Missing or invalid API key.
`404`	Not Found	Edge, source snapshot, or target snapshot not found.
`409`	Conflict	Duplicate edge — an edge of this type already exists between these snapshots.
`422`	Unprocessable	Both snapshots must belong to the same brain.

Specific Knowledge