Reference

Entities

An Entity is a thing with identity: a typed node with a title, aliases, properties and external ids.

Checked 2026-09-28

An Entity is a thing with identity: a typed node with a title, aliases, properties and external ids. Its identity is one per graph (the environment), so one person is one entity across every space; it is visible to a reader who may read its home space or at least one of its facts.

Service Sylphx Knowledge · Resource type knowledge.sylphx.com/Entity · Name pattern orgs/{org}/projects/{project}/envs/{env}/entities/{entity} · Shape record

Not available yet. Sylphx Knowledge is declared in the registry but no backend serves it: every call answers 501 with the problem code UNIMPLEMENTED.

#Fields

Field	Type	What it is
name	string	orgs/{org}/projects/{project}/envs/{env}/entities/{entity}.
uid	string	ken_<26 base32>; never reused. Output only.
meta	ResourceMeta	Resource metadata.
entity_type	string	The type: a core type (person, organisation, customer, contact, product, project, document, decision, playbook, case, topic) or a type of an accepted Knowledge Schema, <schema>.<type>. Required.
title	string	The name people use for it. Required.
aliases	string[]	Other names it is known by; at most 50.
properties	struct	Properties, valid against the type's JSON Schema.
external_ids	ExternalId[]	Identifiers in other systems. Two writes with the same external id in one graph are the same entity (deterministic resolution). At most 50.
space	string	The space the entity was first stated in. Required.
provenance	Provenance	Where it came from and who wrote it. Output only.
lifecycle	EntityLifecycle	Whether the entity stands on its own or was merged into another. Output only. One of active, merged.
survivor	string	The entity this one was merged into, while lifecycle is ENTITY_LIFECYCLE_MERGED. Output only.
merged_entities	string[]	The entities merged into this one; each can be split back out. Output only.
create_time	timestamp	When the entity was first recorded. Output only.
update_time	timestamp	When the entity last changed. Output only.

#Methods

Every method of the collection, in the registry's order, with the scope it needs. The full request, response and examples are one link away.

Method	Call	What it does
GET	get	Gets an entity.
GET	list	Lists the entities the caller may see. The filter is limited to entity_type and lifecycle.
POST	create	Creates an entity in a space. An entity whose external id already names one in the graph is refused with RESOURCE_ALREADY_EXISTS, which names it; use Update with allow_missing to upsert.
PATCH	update	Updates an entity. With allow_missing it is the structured upsert (upsert_entity): an entity matched by external_ids is updated, otherwise one is created.
DELETE	delete	Deletes an entity and every fact about it. With force it is a data-rights erasure: the episodes the person wrote are deleted too, with their search and embedding entries.
POST	merge	Merges other entities into this one: their facts and external ids resolve to it. The merge is recorded and reversible with :split; it is never a silent rewrite.
POST	split	Splits a merged entity back out of this one, with the facts and external ids it brought.
POST	profile	Returns one entity's profile in one call (entity): the entity, its current facts in both directions, the entities they name and the recent episodes about it, trimmed to what the caller may see. A read with a request body.
POST	recall	Searches the graph (recall): hybrid lexical and semantic search over episodes and facts, fused by reciprocal rank, then at most two hops of expansion from the top entities. Returns a context pack with citations, built only from records the caller may see.
POST	ask	Answers a question through Sylphx AI (ask), from a context pack built only from records the caller may see, with citations to its episodes.

#get

Gets an entity.

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity · scope knowledge:read · effect read · not available yet · Request, response and examples

#list

Lists the entities the caller may see. The filter is limited to entity_type and lifecycle.

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities · scope knowledge:read · effect read · not available yet · paginated · Request, response and examples

#create

Creates an entity in a space. An entity whose external id already names one in the graph is refused with RESOURCE_ALREADY_EXISTS, which names it; use Update with allow_missing to upsert.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities · scope knowledge:write · effect write · not available yet · Request, response and examples

#update

Updates an entity. With allow_missing it is the structured upsert (upsert_entity): an entity matched by external_ids is updated, otherwise one is created.

PATCH https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity · scope knowledge:write · effect write · not available yet · Request, response and examples

#delete

Deletes an entity and every fact about it. With force it is a data-rights erasure: the episodes the person wrote are deleted too, with their search and embedding entries.

DELETE https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity · scope knowledge:write · effect destructive · not available yet · Request, response and examples

#merge

Merges other entities into this one: their facts and external ids resolve to it. The merge is recorded and reversible with :split; it is never a silent rewrite.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity:merge · scope knowledge:write · effect write · not available yet · Request, response and examples

#split

Splits a merged entity back out of this one, with the facts and external ids it brought.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity:split · scope knowledge:write · effect write · not available yet · Request, response and examples

#profile

Returns one entity's profile in one call (entity): the entity, its current facts in both directions, the entities they name and the recent episodes about it, trimmed to what the caller may see. A read with a request body.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity:profile · scope knowledge:read · effect read · not available yet · Request, response and examples

#recall

Searches the graph (recall): hybrid lexical and semantic search over episodes and facts, fused by reciprocal rank, then at most two hops of expansion from the top entities. Returns a context pack with citations, built only from records the caller may see.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities:recall · scope knowledge:read · effect read · not available yet · Request, response and examples

#ask

Answers a question through Sylphx AI (ask), from a context pack built only from records the caller may see, with citations to its episodes.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities:ask · scope knowledge:read · effect read · not available yet · Request, response and examples