> ## Documentation Index
> Fetch the complete documentation index at: https://seal-d2ca5bea.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity object

> How an entity is represented when you read or write it through the SDK or as files on disk.

Every entity in Seal has the same outer shape — metadata, fields, and
**one** body of content. The body's format depends on the entity's
content type. This page is the hub for that shape; the other pages in
this section describe each content type in detail.

## At a glance

```python theme={null}
entity.id                       # 'ent_8a1c…'
entity.title                    # 'Buffer Recipe'
entity.status                   # 'IN_PROGRESS' | 'FINISHED' | …
entity.type                     # the entity-type slug
entity.system                   # the system slug
entity.fields["Volume (mL)"]    # Field { value, config }
entity.content.type             # 'page_content' | 'script_code' | 'chart' | …
entity.content.value            # depends on .type — see table below
```

`entity.fields` and `entity.content` are the only two places content
lives. Tags, comments, permissions, change-control state, and audit
history all hang off the same entity but are not "content" — they live
on `entity.tags`, `entity.comments`, etc.

## File representation

When you `seal pull` an entity, you get a directory:

```
ent_8a1c/
  entity.json            # metadata, fields, refs — everything except the body
  content.<ext>          # the body — extension depends on content type
  .seal/
    manifest.json        # id, version, lastUpdatedAt, content digest
```

`entity.json` is human-readable and edit-safe; `seal commit` will pick
up your changes. The body file is whatever shape the content type
demands (see table below).

Round-trip: read → edit → write preserves everything the SDK supports.
Anything the SDK can't represent natively round-trips through opaque
preservation rather than being silently dropped.

## Content types

| `entity.content.type`            | Body format                 | Body filename               |
| -------------------------------- | --------------------------- | --------------------------- |
| `page_content`                   | Markdown (Seal flavor)      | `content.md`                |
| `script_code` / `script_code_v2` | Python or JavaScript source | `content.py` / `content.js` |
| `chart`                          | JSON (Vega-Lite spec)       | `content.json`              |
| `file`                           | The file itself             | `content.<ext>`             |
| `custom`                         | Source string or zip        | `content.<ext>`             |
| `none`                           | *(no body)*                 | *(absent)*                  |

Most entity types have a `content.type` of `none` — they're pure
field-and-metadata records. Page content, scripts, charts, and files
are the four content-bearing types.

## Reading and writing

```python theme={null}
# Read
entity = seal.entities.get("ent_8a1c…")
entity.title                              # metadata
entity.fields["Volume (mL)"].value        # a field
entity.content.value                      # the body — string, dict, or Path

# Write
seal.entities.update(
    entity,
    title="Buffer Recipe (revised)",
    fields={"Volume (mL)": 250},
    content="# New body\n\n…",            # body shape matches content.type
)
```

The shape you read at `entity.content.value` is the same shape you
write back. For `page_content` that's a Markdown string; for
`script_code` it's source text; for `chart` it's a Vega-Lite dict; for
`file` it's a file id on read or a `Path` on write.

## Per-content-type detail

<CardGroup cols={2}>
  <Card title="Fields" href="/entity-content/fields">
    The structured part of every entity — types, configs, formulas, and
    how each field type reads and writes.
  </Card>

  <Card title="Page content" href="/entity-content/page-content">
    Rich documents stored as Seal-flavored Markdown, with field cards,
    tasks, mentions, and layout components.
  </Card>

  <Card title="Files" href="/entity-content/files">
    Uploaded files — images, PDFs, raw data — referenced by other
    entities or stored standalone.
  </Card>

  <Card title="Scripts" href="/entity-content/scripts">
    Python / JavaScript source attached to an entity, run on triggers
    or on demand.
  </Card>

  <Card title="Charts" href="/entity-content/charts">
    Vega-Lite specifications rendered against entity data.
  </Card>

  <Card title="Custom content">
    First-class support for your own content types via deployable
    bundles. See [Custom content](/entity-content/custom-content).
  </Card>
</CardGroup>

## Coming soon

The entity-object surface continues to expand. The following are
planned and will appear here when they ship:

* **Folders** — entities that hold a structured collection of
  references, with their own configurable display.
* **Forms** — entities whose body is a fillable form template.
* **Workflows** — long-running orchestrations expressed as entities.

Each will follow the same outer shape — metadata, fields, one body —
so existing SDK code keeps working as new types land.