Data Management

Create, update, and delete entities, relations, and chunks within your knowledge graphs. These endpoints provide full CRUD operations with granular control over your graph data and best-effort synchronization across SQL, Qdrant, and Neo4j storage layers.

Best-Effort Synchronization

Data management operations attempt to synchronize across all storage backends (SQL, Qdrant, Neo4j). Failures in one backend do not prevent updates to others. Check response metadata for detailed synchronization status.

POST

/data/entity/{kg_name}

Create a new entity in a knowledge graph. Entities represent nodes in the knowledge graph and can have labels, types, and custom properties.

Request Body

Field	Type	Required	Description
`label`	string	Yes	Entity label/name (1-500 characters)
`entity_type`	string	Yes	Type of entity (1-100 characters, e.g., DISEASE, PERSON, ORGANIZATION)
`properties`	object	No	Custom properties/metadata for the entity
`sync_to_qdrant`	boolean	No	Automatically create vector embedding in Qdrant (default: true)
`sync_to_neo4j`	boolean	No	Sync to Neo4j graph if available (default: false)

PUT

/data/entity/{kg_name}/{entity_id}

Update properties of a specific entity in a knowledge graph. You can update the entity description and custom properties stored in the properties JSON field.

Request Body

Field	Type	Required	Description
`description`	string	No	Updated description for the entity
`properties`	object	No	Custom properties to update (merged with existing)

DELETE

/data/entity/{kg_name}/{entity_id}

Delete a specific entity and its associated relations from the knowledge graph. This operation cascades to remove all relations where this entity is either the source or target.

Cascade Deletion

Deleting an entity will also remove all relations connected to it. This operation cannot be undone. Ensure you have backups if needed.

DELETE

/data/entities/bulk/{kg_name}

Delete multiple entities from a knowledge graph in a single operation. This is more efficient than deleting entities one by one. The operation returns detailed results including which entities were successfully deleted and which failed.

Bulk Deletion

Bulk deletion also cascades to remove all relations connected to the deleted entities. This operation cannot be undone. Always maintain backups before bulk operations.

Request Body

Field	Type	Required	Description
`ids`	array of integers	Yes	List of entity IDs to delete (minimum 1 ID required)

POST

/data/relation/{kg_name}

Create a new relation between two entities in a knowledge graph. Relations represent connections or relationships between entities and can have types, confidence scores, and custom properties.

Request Body

Field	Type	Required	Description
`relation_type`	string	Yes	Type of relation (1-100 characters, e.g., TREATS, CAUSES, RELATED_TO)
`source_entity_id`	integer	Yes	ID of the source entity (must be positive)
`target_entity_id`	integer	Yes	ID of the target entity (must be positive)
`confidence_score`	float	No	Confidence score for the relation (0.0-1.0)
`properties`	object	No	Custom properties/metadata for the relation
`sync_to_neo4j`	boolean	No	Sync to Neo4j graph if available (default: false)

PUT

/data/relation/{kg_name}/{relation_id}

Update the type or properties of a specific relation in the knowledge graph. Currently supports updating the relation type and custom properties.

Request Body

Field	Type	Required	Description
`relation_type`	string	No	Updated relation type (e.g., CAUSES, TREATS, RELATED_TO)
`properties`	object	No	Custom properties for the relation

DELETE

/data/relation/{kg_name}/{relation_id}

Delete a specific relation from the knowledge graph. This removes the connection between two entities but does not delete the entities themselves.

DELETE

/data/relations/bulk/{kg_name}

Delete multiple relations from a knowledge graph in a single operation. This is more efficient than deleting relations one by one. The operation returns detailed results including which relations were successfully deleted and which failed.

Request Body

Field	Type	Required	Description
`ids`	array of integers	Yes	List of relation IDs to delete (minimum 1 ID required)

POST

/data/chunk/{kg_name}

Create a new text chunk in a knowledge graph. Chunks represent pieces of text content that can be used for semantic search and retrieval. Chunks are stored in both SQL and vector databases for efficient querying.

Request Body

Field	Type	Required	Description
`content`	string	Yes	Chunk content text (minimum 1 character)
`metadata`	object	No	Custom metadata for the chunk (e.g., source, page number, section)
`entity_ids`	array of integers	No	List of associated Entity IDs
`sync_to_qdrant`	boolean	No	Automatically create vector embedding in Qdrant (default: true)

DELETE

/data/chunk/{kg_name}/{chunk_id}

Delete a specific text chunk from the knowledge graph. This removes the chunk from both SQL storage and the Qdrant vector database.

Error Responses

Entity/Relation/Chunk Not Found

{
  "detail": "Entity with id 123 not found in KG_Universal",
  "status_code": 404
}

Invalid Create Data

{
  "detail": "Entity label cannot be empty",
  "status_code": 400,
  "field": "label"
}

Invalid Update Data

{
  "detail": "Invalid update data: properties must be a valid JSON object",
  "status_code": 400
}

Bulk Delete Errors

{
  "success": false,
  "deleted_count": 2,
  "failed_count": 2,
  "failed_ids": [789, 101112],
  "message": "Some entities could not be deleted",
  "errors": {
    "789": "Entity not found",
    "101112": "Entity is referenced by active relations"
  }
}

Best Practices

Backup: Always maintain backups before bulk delete operations
Validation: Verify entity/relation/chunk IDs before deletion
Updates: Use partial updates - only specify fields you want to change
Properties: Store metadata in properties for flexible querying
Cascade Effects: Remember that deleting entities also deletes related connections
Monitoring: Check response metadata for synchronization status across backends

Data management operations are authenticated and require a valid API key. All operations are logged for audit purposes.