Relations & Graph

Relations connect ideas to each other, forming a navigable graph. Each relation has a source, a target, a type, and an optional note.

List Relations for an Idea

GET /api/v1/ideas/:id/relations

Returns all relations involving the specified idea, grouped by direction (outgoing and incoming).

curl

curl https://neuralrepo.com/api/v1/ideas/42/relations \
  -H "X-API-Key: nrp_YOUR_KEY"

JavaScript

const res = await fetch(
  "https://neuralrepo.com/api/v1/ideas/42/relations",
  { headers: { "X-API-Key": "nrp_YOUR_KEY" } }
);
const relations = await res.json();

Response 200 OK

{
  "outgoing": [
    {
      "id": 1,
      "source_idea_id": 42,
      "target_idea_id": 18,
      "relation_type": "related",
      "note": "Both deal with theming",
      "created_at": "2026-03-20T10:00:00Z"
    }
  ],
  "incoming": [
    {
      "id": 2,
      "source_idea_id": 7,
      "target_idea_id": 42,
      "relation_type": "blocks",
      "note": null,
      "created_at": "2026-03-19T08:00:00Z"
    }
  ]
}

Create Relation

POST /api/v1/map/relations

Request Body

Field	Type	Required	Description
source_idea_id	number	Yes	ID of the source idea
target_idea_id	number	Yes	ID of the target idea
relation_type	string	No	Type of relation (default: related)
note	string	No	Description, max 500 characters

curl

curl -X POST https://neuralrepo.com/api/v1/map/relations \
  -H "X-API-Key: nrp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_idea_id": 42,
    "target_idea_id": 18,
    "relation_type": "related",
    "note": "Both deal with theming"
  }'

JavaScript

const res = await fetch("https://neuralrepo.com/api/v1/map/relations", {
  method: "POST",
  headers: {
    "X-API-Key": "nrp_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source_idea_id: 42,
    target_idea_id: 18,
    relation_type: "related",
    note: "Both deal with theming",
  }),
});
const relation = await res.json();

Response 201 Created

{
  "id": 1,
  "source_idea_id": 42,
  "target_idea_id": 18,
  "relation_type": "related",
  "note": "Both deal with theming",
  "created_at": "2026-03-24T09:00:00Z"
}

Update Relation

PATCH /api/v1/map/relations/:id

Request Body

Field	Type	Required	Description
relation_type	string	No	New relation type
note	string	No	Updated note, max 500 characters

curl -X PATCH https://neuralrepo.com/api/v1/map/relations/1 \
  -H "X-API-Key: nrp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"relation_type": "blocks"}'

Response 200 OK — Returns the updated relation object.

Delete Relation

DELETE /api/v1/map/relations/:id

curl -X DELETE https://neuralrepo.com/api/v1/map/relations/1 \
  -H "X-API-Key: nrp_YOUR_KEY"

Response 204 No Content

Cycle Detection

When creating or updating relations, the API checks for circular dependencies on certain relation types. The behavior depends on the type of relation:

Hard block (always rejected)

Relations of type blocks and parent are never allowed to form cycles. If adding such a relation would create a cycle, the request is rejected with 409 Conflict:

{
  "error": "Relation would create a cycle"
}

There is no way to override this check for these types.

Soft block (force override available)

Relations of type supersedes are checked for cycles by default. If a cycle is detected, the request is rejected with 409 Conflict. However, you can bypass this check by adding ?force=true:

curl -X POST "https://neuralrepo.com/api/v1/map/relations?force=true" \
  -H "X-API-Key: nrp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_idea_id": 18,
    "target_idea_id": 42,
    "relation_type": "supersedes"
  }'

No cycle check

Relations of type related, inspires, and duplicate do not perform cycle detection. These types are inherently non-directional or non-hierarchical, so cycles are allowed.

Caution

Use ?force=true carefully with supersedes relations. Cycles in directional relation types can cause unexpected behavior in graph views.

Relation Schema

Field	Type	Description
id	number	Unique relation identifier
source_idea_id	number	ID of the source idea
target_idea_id	number	ID of the target idea
relation_type	string	related, parent, blocks, inspires, duplicate, supersedes
note	string | null	Optional description
created_at	string	ISO 8601 timestamp

Status Codes

Status	Meaning
200 OK	Successful read or update
201 Created	Relation created
204 No Content	Relation deleted
400 Bad Request	Validation error
401 Unauthorized	Missing or invalid auth
404 Not Found	Relation or idea not found
409 Conflict	Cycle detected