Relations

The Relations API creates, reads, and removes explicit links between Viking URIs.

API Reference

link()

Create relations between resources.

Parameters

Parameter	Type	Required	Default	Description
from_uri	str	Yes	-	Source URI
to_uris	str or List[str]	Yes	-	Target URI(s)
reason	str	No	""	Reason for the link

Python SDK

# Single link
client.link(
    "viking://resources/docs/auth/",
    "viking://resources/docs/security/",
    reason="Security best practices for authentication"
)

# Multiple links
client.link(
    "viking://resources/docs/api/",
    [
        "viking://resources/docs/auth/",
        "viking://resources/docs/errors/"
    ],
    reason="Related documentation"
)

TypeScript SDK

await client.link(
  "viking://resources/docs/api/",
  [
    "viking://resources/docs/auth/",
    "viking://resources/docs/errors/",
  ],
  "Related documentation",
);

HTTP API

POST /api/v1/relations/link

# Single link
curl -X POST http://localhost:1933/api/v1/relations/link \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "from_uri": "viking://resources/docs/auth/",
    "to_uris": "viking://resources/docs/security/",
    "reason": "Security best practices for authentication"
  }'

# Multiple links
curl -X POST http://localhost:1933/api/v1/relations/link \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "from_uri": "viking://resources/docs/api/",
    "to_uris": ["viking://resources/docs/auth/", "viking://resources/docs/errors/"],
    "reason": "Related documentation"
  }'

CLI

openviking link viking://resources/docs/auth/ viking://resources/docs/security/ --reason "Security best practices"

Response

{
  "status": "ok",
  "result": {
    "from": "viking://resources/docs/auth/",
    "to": "viking://resources/docs/security/"
  },
  "time": 0.1
}

---

relations()

Get relations for a resource.

Parameters

Parameter	Type	Required	Default	Description
uri	str	Yes	-	Viking URI

Python SDK

relations = client.relations("viking://resources/docs/auth/")
for rel in relations:
    print(f"Related: {rel['uri']}")
    print(f"  Reason: {rel['reason']}")

TypeScript SDK

const relations = await client.relations("viking://resources/docs/auth/");
console.log(relations);

HTTP API

GET /api/v1/relations?uri={uri}

curl -X GET "http://localhost:1933/api/v1/relations?uri=viking://resources/docs/auth/" \
  -H "X-API-Key: your-key"

CLI

openviking relations viking://resources/docs/auth/

Response

{
  "status": "ok",
  "result": [
    {"uri": "viking://resources/docs/security/", "reason": "Security best practices"},
    {"uri": "viking://resources/docs/errors/", "reason": "Error handling"}
  ],
  "time": 0.1
}

---

unlink()

Remove a relation.

Parameters

Parameter	Type	Required	Default	Description
from_uri	str	Yes	-	Source URI
to_uri	str	Yes	-	Target URI to unlink

Python SDK

client.unlink(
    "viking://resources/docs/auth/",
    "viking://resources/docs/security/"
)

TypeScript SDK

await client.unlink(
  "viking://resources/docs/auth/",
  "viking://resources/docs/security/",
);

HTTP API

DELETE /api/v1/relations/link

curl -X DELETE http://localhost:1933/api/v1/relations/link \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "from_uri": "viking://resources/docs/auth/",
    "to_uri": "viking://resources/docs/security/"
  }'

CLI

openviking unlink viking://resources/docs/auth/ viking://resources/docs/security/

Response

{
  "status": "ok",
  "result": {
    "from": "viking://resources/docs/auth/",
    "to": "viking://resources/docs/security/"
  },
  "time": 0.1
}

---

build_graph()

Generate a self-contained HTML relation graph from multiple memory roots and write it to a Viking URI.

Parameter	Type	Required	Description
space_uris	string[]	Yes	Memory roots to merge
output_uri	string	Yes	Viking URI of the output HTML file

HTTP API

POST /api/v1/relations/build_graph
Content-Type: application/json

curl -X POST http://localhost:1933/api/v1/relations/build_graph \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "space_uris":[
      "viking://user/default/memories",
      "viking://user/default/peers/project-a/memories"
    ],
    "output_uri":"viking://user/default/memories/.graph.html"
  }'

Response

{
  "status": "ok",
  "result": {
    "graph_uri": "viking://user/default/memories/.graph.html"
  }
}

graph_uri is the URI of the generated self-contained HTML file. Read it through the content or filesystem API.

This endpoint does not currently have a public SDK or CLI wrapper, so this section shows only the HTTP tab.

---

Related Documentation

• Retrieval - retrieve and use related content
• File System - manage relation targets
• Memory - memory namespaces and types