Skip to main content

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.

Every item carries a metadata layer regardless of type. Three fields, all at the top level of the item:
FieldTypePurpose
tagsarray of stringsFlat labels. Kebab-case.
tierenumlibrary or feed. See Tier.
stateenumactive / archived / trashed. See 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 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 via ?tags=work,urgent (AND semantics). Mutate tags via the dedicated metadata endpoints — see PUT /items/{id}/metadata for shapes.
Tag changes on the same item from different clients auto-merge as set union. Adding a tag wins over a concurrent remove.

​
Reserved prefixes

Marfa protects a few tag prefixes for cross-app conventions. Apps choose whether to use them; the prefixes themselves are not required.
PrefixMeaning
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

TagMeaning
favoriteA 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.

​
Tier

Top-level enum. See Tier 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 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. 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 — per-namespace, scoped per credential.