Skip to main content

Knowledge Graph

The Knowledge Graph router lets you create structured relationships between entities using subject-predicate-object triples. Entities are auto-created when referenced in a triple.

Base URL: https://novyx-ram-api.fly.dev

Tier: Pro+

Backend: Requires Postgres

Create Triple​

POST /v1/knowledge/triples

Create a relationship between two entities. Entity names are auto-normalized to lowercase. If the subject or object entity doesn't exist yet, it's created automatically.

Request body​

ParameterTypeRequiredDefaultDescription
subjectstringYes—Subject entity name
predicatestringYes—Relationship type (e.g., prefers, works_at)
objectstringYes—Object entity name
confidencenumberNo1.0Confidence score (0.0–1.0)
source_memory_idstringNo—UUID linking this triple to a source memory
subject_typestringNo—Entity type for auto-created subject
object_typestringNo—Entity type for auto-created object
metadataobjectNo—Custom metadata

Response fields​

FieldTypeDescription
triple_idstringUnique triple identifier
subjectobjectFull subject entity (id, name, type)
predicatestringRelationship type
objectobjectFull object entity (id, name, type)
confidencenumberConfidence score
source_memory_idstring | nullLinked source memory
metadataobjectCustom metadata
created_atstringISO 8601 timestamp

Examples​

from novyx import Novyx

nx = Novyx(api_key="nram_your_key")

triple = nx.add_triple(
    subject="alice",
    predicate="works_at",
    object="novyx",
    confidence=0.95,
    subject_type="person",
    object_type="company",
)
print(triple["triple_id"])

Response​

{
  "triple_id": "urn:uuid:t1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "subject": {
    "entity_id": "urn:uuid:e1a2b3c4-0001-0000-0000-000000000001",
    "name": "alice",
    "entity_type": "person"
  },
  "predicate": "works_at",
  "object": {
    "entity_id": "urn:uuid:e1a2b3c4-0001-0000-0000-000000000002",
    "name": "novyx",
    "entity_type": "company"
  },
  "confidence": 0.95,
  "source_memory_id": null,
  "metadata": {},
  "created_at": "2026-03-09T12:00:00Z"
}

Errors​

StatusCodeCause
403FEATURE_NOT_AVAILABLERequires Pro+ plan
404NOT_FOUNDsource_memory_id does not exist
501REQUIRES_POSTGRESPostgres backend required

Query Triples​

GET /v1/knowledge/triples

List triples with optional filters. Results are sorted by creation date (newest first).

Query parameters​

ParameterTypeRequiredDefaultDescription
subjectstringNo—Filter by subject entity name
predicatestringNo—Filter by predicate
objectstringNo—Filter by object entity name
source_memory_idstringNo—Filter by linked source memory
limitnumberNo50Max results (1–500)
offsetnumberNo0Pagination offset

Response fields​

FieldTypeDescription
triplesarrayArray of triple objects
totalnumberTotal matching triples

Examples​

# All triples for a subject
triples = nx.query_triples(subject="alice")

# Filter by predicate
works = nx.query_triples(predicate="works_at", limit=10)

Response​

{
  "triples": [
    {
      "triple_id": "urn:uuid:t1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "subject": {
        "entity_id": "urn:uuid:e1a2b3c4-0001-0000-0000-000000000001",
        "name": "alice",
        "entity_type": "person"
      },
      "predicate": "works_at",
      "object": {
        "entity_id": "urn:uuid:e1a2b3c4-0001-0000-0000-000000000002",
        "name": "novyx",
        "entity_type": "company"
      },
      "confidence": 0.95,
      "source_memory_id": null,
      "metadata": {},
      "created_at": "2026-03-09T12:00:00Z"
    }
  ],
  "total": 1
}

Get Triple​

GET /v1/knowledge/triples/{triple_id}

Retrieve a single triple by ID.

Path parameters​

ParameterTypeDescription
triple_idstringTriple identifier

Examples​

triple = nx.get_triple("urn:uuid:t1a2b3c4-d5e6-7890-abcd-ef1234567890")
print(f"{triple['subject']['name']} → {triple['predicate']} → {triple['object']['name']}")

Errors​

StatusCodeCause
404NOT_FOUNDTriple does not exist

Delete Triple​

DELETE /v1/knowledge/triples/{triple_id}

Delete a triple. Does not delete the associated entities.

Path parameters​

ParameterTypeDescription
triple_idstringTriple identifier

Examples​

result = nx.delete_triple("urn:uuid:t1a2b3c4-d5e6-7890-abcd-ef1234567890")
print(result["deleted"])  # True

Response​

{
  "deleted": true
}

Errors​

StatusCodeCause
404NOT_FOUNDTriple does not exist

List Entities​

GET /v1/knowledge/entities

List all entities in the knowledge graph with optional filters.

Query parameters​

ParameterTypeRequiredDefaultDescription
entity_typestringNo—Filter by entity type
qstringNo—Name prefix search (case-insensitive)
limitnumberNo50Max results (1–500)
offsetnumberNo0Pagination offset

Response fields​

FieldTypeDescription
entitiesarrayArray of entity objects
totalnumberTotal matching entities

Each entity includes:

FieldTypeDescription
entity_idstringUnique entity identifier
namestringEntity name (lowercase)
entity_typestringEntity type
metadataobjectCustom metadata
created_atstringISO 8601 timestamp
triple_countnumberNumber of triples referencing this entity

Examples​

# List all entities
entities = nx.list_entities()

# Filter by type
people = nx.list_entities(entity_type="person")

# Search by name prefix
results = nx.list_entities(q="ali")

Response​

{
  "entities": [
    {
      "entity_id": "urn:uuid:e1a2b3c4-0001-0000-0000-000000000001",
      "name": "alice",
      "entity_type": "person",
      "metadata": {},
      "created_at": "2026-03-09T12:00:00Z",
      "triple_count": 3
    }
  ],
  "total": 1
}

Entity Traversal​

GET /v1/knowledge/entities/{entity_id}

Get an entity with all its connections — triples where it appears as subject or object.

Path parameters​

ParameterTypeDescription
entity_idstringEntity identifier

Response fields​

FieldTypeDescription
entityobjectFull entity details
as_subjectarrayTriples where this entity is the subject
as_objectarrayTriples where this entity is the object
total_connectionsnumberTotal triples in both directions

Examples​

traversal = nx.get_entity("urn:uuid:e1a2b3c4-0001-0000-0000-000000000001")
print(f"{traversal['entity']['name']} has {traversal['total_connections']} connections")

for t in traversal["as_subject"]:
    print(f"  → {t['predicate']} → {t['object']['name']}")

Response​

{
  "entity": {
    "entity_id": "urn:uuid:e1a2b3c4-0001-0000-0000-000000000001",
    "name": "alice",
    "entity_type": "person",
    "metadata": {},
    "created_at": "2026-03-09T12:00:00Z"
  },
  "as_subject": [
    {
      "triple_id": "urn:uuid:t1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "predicate": "works_at",
      "object": {
        "entity_id": "urn:uuid:e1a2b3c4-0001-0000-0000-000000000002",
        "name": "novyx",
        "entity_type": "company"
      },
      "confidence": 0.95,
      "created_at": "2026-03-09T12:00:00Z"
    }
  ],
  "as_object": [],
  "total_connections": 1
}

Errors​

StatusCodeCause
404NOT_FOUNDEntity does not exist

Delete Entity​

DELETE /v1/knowledge/entities/{entity_id}

Delete an entity and cascade-delete all triples that reference it.

Path parameters​

ParameterTypeDescription
entity_idstringEntity identifier

Examples​

result = nx.delete_entity("urn:uuid:e1a2b3c4-0001-0000-0000-000000000001")
print(f"Deleted, removed {result['triples_removed']} triples")

Response​

{
  "deleted": true,
  "triples_removed": 3
}

Errors​

StatusCodeCause
404NOT_FOUNDEntity does not exist