> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity

> An entity is one thing the Graph holds, with a type from a Shape, properties and a revision, and you delete it softly.

Concept · graph

> **Use when**
>
> You find, read, change, delete or restore one thing the Graph holds.

> **Looking for something else?**
>
> Several changes at once (card [Workspace](https://docs.pnbr.io/concepts/workspace.md)). A connection between two entities (card [Relationship](https://docs.pnbr.io/concepts/relationship.md)). A document you keep as a File (card [File](https://docs.pnbr.io/concepts/file.md)).

## For

An entity has a name, a description, a type from a published Shape, properties
and a revision number. Each change gives the entity a new revision. A deleted
entity keeps its history, and you can restore it.

## Use when

* You look up an entity by name or by id.
* You change the name, description or properties of one entity.
* You delete one entity, or bring a deleted entity back.

## Not this

* Several new or changed entities in one reviewed step: use a workspace (card
  workspace).
* A relationship between two entities: use card [Relationship](https://docs.pnbr.io/concepts/relationship.md).
* A document with text people edit: use card [Document](https://docs.pnbr.io/concepts/document.md).

## Rules

1. `entity.1` Change an entity at the revision you read. Pass it to
   `penumbra graph update` as `--revision`. **Enforced when you ask:** an entity
   that moved on is refused. The MCP tool `update_node` answers
   `revision_conflict`. Without `--revision`,
   the CLI reads the entity at that moment and uses that revision. A change made
   between your own read and that call is then not caught.
2. `entity.2` A direct update replaces the whole property map, and a workspace
   patch merges into it. `penumbra graph update` and the MCP tool `update_node`
   remove every property you leave out. A patch staged with
   `penumbra graph workspace modify` keeps the properties you leave out.
   **Your job:** in a direct update, send every property you want to keep. A new
   item that you staged in the workspace has no earlier map, so an edit of its
   `properties` replaces the whole map.
3. `entity.3` Deleting is soft. `penumbra graph delete` deletes the entity and
   the relationships that touch it. The entity keeps its history.
   `penumbra graph restore` brings back the entity only. **Your job:** restore
   the relationships yourself. Find a deleted entity by id, not by name.
4. `entity.4` A delete waits for approval when an API key or a connected agent
   makes it. **Enforced:** the result is `pending` with an approval URL. A
   restore does not wait. A workspace that deletes entities waits as well, as
   rule [workspace.10](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-10) and card [Approval](https://docs.pnbr.io/concepts/approval.md) say.
5. `entity.5` Properties must fit the entity's type in its Shape. **Enforced:**
   validate and submit report an error diagnostic, such as
   `schema_validation_failed`, and apply nothing. **Your job:** read the type in
   its Shape with `penumbra shapes show` before you stage properties.
6. `entity.6` A citation belongs to the revision where it was written. **Your
   job:** when you edit a checked-out entity, cite the passage that supports the
   new value. The citations on the old revision are history. They are not copied
   forward as support for your edit (card [Passage and citation](https://docs.pnbr.io/concepts/passage.md)).

## Failure signs

* An update is refused with `version_conflict` or `revision_conflict`: read the
  entity again with `penumbra graph get <id>`, then change it at the new
  revision (rule [entity.1](https://docs.pnbr.io/concepts/entity.md#rule-entity-1)).
* A delete returns `pending`: problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md).
* A restored entity has no relationships: rule [entity.3](https://docs.pnbr.io/concepts/entity.md#rule-entity-3).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra graph search`, `penumbra graph get`, `penumbra graph nodes`, `penumbra graph traverse`, `penumbra graph update`, `penumbra graph delete`, `penumbra graph restore` |
| MCP (default) | `read` with the reference `entity:<id>`. Changes go through a workspace (card [Workspace](https://docs.pnbr.io/concepts/workspace.md)). |
| MCP (full catalog) | `search_graph`, `traverse_graph`, `update_node`, `delete_node`, `restore_node` |
| SDK | `ProjectGraph.getNode`, `ProjectGraph.updateNode`, `ProjectGraph.deleteNode`, `ProjectGraph.restoreNode` |

The Kit levels read, propose, confirm and apply do not include `update_node`,
`delete_node` or `restore_node`. A Kit at those levels changes entities through
a workspace.

## The CLI word

The CLI calls an entity a node in `penumbra graph nodes` and `penumbra graph traverse`.
The CLI calls an entity a record and a citation a quote in `penumbra evidence list`.

## HTTP reference

* [List graph nodes](https://docs.pnbr.io/api/http-graph-nodes-list.md)
* [Get graph node](https://docs.pnbr.io/api/http-graph-nodes-get.md)
* [Get node history](https://docs.pnbr.io/api/http-graph-nodes-history.md)
* [List graph edges](https://docs.pnbr.io/api/http-graph-edges-list.md)
* [Get graph edge](https://docs.pnbr.io/api/http-graph-edges-get.md)
* [Get edge history](https://docs.pnbr.io/api/http-graph-edges-history.md)
* [Count graph records](https://docs.pnbr.io/api/http-graph-counts.md)
* [Traverse graph](https://docs.pnbr.io/api/http-graph-traverse.md)
* [List graph commits](https://docs.pnbr.io/api/http-graph-commits-list.md)
* [Get graph commit](https://docs.pnbr.io/api/http-graph-commits-get.md)

## Keep going

[Workspace](https://docs.pnbr.io/concepts/workspace.md) · [Relationship](https://docs.pnbr.io/concepts/relationship.md) · [Approval](https://docs.pnbr.io/concepts/approval.md) · [Shape](https://docs.pnbr.io/concepts/shape.md) · [Passage and citation](https://docs.pnbr.io/concepts/passage.md)

Penumbra Grammar 0.6.26


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.