---
# @generated by sylphx-gen 0.1.0 from contracts@fb95f0c42a0ec5d8e3cb694c0054b529c0b24b184112c65ef60c9044b4ce61f9. Do not edit.
title: "Entities"
description: "The `entities` collection of Sylphx Knowledge: An Entity is a thing with identity: a typed node with a title, aliases, properties and external ids."
type: reference
product: knowledge
summary: "An Entity is a thing with identity: a typed node with a title, aliases, properties and external ids."
updated: 2026-09-28
order: 900
---

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`](/docs/api/entities#get) | Gets an entity. |
| `GET` | [`list`](/docs/api/entities#list) | Lists the entities the caller may see. The filter is limited to `entity_type` and `lifecycle`. |
| `POST` | [`create`](/docs/api/entities#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`](/docs/api/entities#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`](/docs/api/entities#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`](/docs/api/entities#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`](/docs/api/entities#split) | Splits a merged entity back out of this one, with the facts and external ids it brought. |
| `POST` | [`profile`](/docs/api/entities#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`](/docs/api/entities#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`](/docs/api/entities#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](/docs/api/entities/get)

## 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](/docs/api/entities/list)

## 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](/docs/api/entities/create)

## 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](/docs/api/entities/update)

## 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](/docs/api/entities/delete)

## 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](/docs/api/entities/merge)

## 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](/docs/api/entities/split)

## 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](/docs/api/entities/profile)

## 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](/docs/api/entities/recall)

## 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](/docs/api/entities/ask)