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

# Metadata

> Tags, tier, state — the universal layer applied to every item

Every item carries a metadata layer regardless of type. Three fields, all at the top level of the item:

| Field   | Type             | Purpose                                                                  |
| ------- | ---------------- | ------------------------------------------------------------------------ |
| `tags`  | array of strings | Flat labels. Kebab-case.                                                 |
| `tier`  | enum             | `library` or `feed`. See [Tier](/concepts/library).                      |
| `state` | enum             | `active` / `archived` / `trashed`. See [Lifecycle](/concepts/lifecycle). |

The metadata layer is **closed** — types cannot add to it. These three fields hold the concepts that have system-wide consequences: labels, the curation axis, lifecycle. Additional always-present fields belong in `properties` on the type.

[`system.*` items](/concepts/system-types) are the exception: they don't carry the metadata layer at all. They're operational, not user content, and the dimensions don't apply.

## Tags

Tags are flat, kebab-case strings. Zero or more per item. Meant for quick cross-cutting classification.

Filter items by tags on [`GET /items`](/api-reference/items/list-items) via `?tags=work,urgent` (AND semantics). Mutate tags via the dedicated metadata endpoints — see [`PUT /items/{id}/metadata`](/api-reference/items/replace-item-metadata-tags) for shapes.

<Info>
  Tag changes on the same item from different clients auto-merge as set union. Adding a tag wins over a concurrent remove.
</Info>

### Reserved prefixes

Marfa protects a few tag prefixes for cross-app conventions. Apps choose whether to use them; the prefixes themselves are not required.

| Prefix             | Meaning                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| `collection:<id>`  | Membership in a named grouping. Paired with a custom group item that holds the collection's metadata. |
| `folder:<name>`    | Hierarchical structural grouping.                                                                     |
| `status:<value>`   | Workflow or status marker.                                                                            |
| `priority:<value>` | Urgency or ranking.                                                                                   |

The canonical mechanism for collection-like grouping is a `parent-of` edge from a custom group item to its members. The `collection:<id>` tag prefix is a convenience back-reference for cross-app reads — both can coexist.

### Reserved flat tags

| Tag        | Meaning                                                                                                                                                                                    |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `favorite` | A user "star" or "love" on the item. Any app's star UI toggles this tag. Kept as a tag rather than a structural field because it has no system-level consequences — it's a pure UI signal. |

### Listing all tags

Enumerate the distinct set of tags in use across items the caller can read:

```
GET /metadata/tags
```

Returns each tag with a usage count, sorted by count descending then tag ascending. Space-scoped, type-permission scoped, excludes trashed items. Use this to populate tag pickers, autocomplete, or "all tags" UI without iterating items.

SDKs expose it as `client.metadata.listTags()`.

### Consuming per-item metadata in UIs

For Swift-side reactive consumption — `ItemsWithMetadataQuery`, `store.queryItemsWithMetadata(filters:)` — see [Swift SDK — Data access](/sdks/swift/data-access).

## Tier

Top-level enum. See [Tier](/concepts/library) for the full treatment — retention, storage tier, permissions.

Set at creation by the credential's `default_tier` (overridable client-side). Mutable post-creation: pass `tier: "library"` or `tier: "feed"` to `PATCH /items/{id}` to flip the value without touching properties or version. The flip never conflicts — it's a single metadata-axis decision, last-writer-wins. Item-type semantics (e.g. promoting a `paste.clip` to a `core.note`) remain per-app.

## State

Lifecycle stage: `active`, `archived`, `trashed`. See [Lifecycle](/concepts/lifecycle) for transitions and the dedicated endpoints.

## What metadata does not hold

* **`about` references.** Not a metadata field. `about` is one of the core [edge types](/concepts/edges). Item responses expose an `about: [...]` convenience array hydrated from those edges for read ergonomics, but the write surface is edges.
* **App-specific fields.** These belong in properties on a custom type, not in metadata. Metadata is for universal concepts.
* **Ephemeral sidecar state.** Use [extensions](/concepts/extensions) — per-namespace, scoped per credential.