ℹ️
What is a Holon?

A Holon is a self-contained data object with an ID, type, metadata, and an arbitrary key-value property bag. See Holons & Data Model for the full conceptual overview.

Save Holon

POST/data/SaveHolon

Persists a holon. Creates a new record if no id is provided; updates the existing record if id is present.

Request body

FieldTypeDescription
holonrequiredobjectThe Holon object to persist (see schema below)
providerTypestringOverride the default provider for this write
setGloballybooleanIf true, also sets as the global default provider

Holon schema

json
{
  "id":          "3fa85f64-…",   // omit to auto-generate
  "name":        "My Holon",
  "description": "…",
  "holonType":   "Custom",
  "metaData":    { "key": "value" },
  "createdByAvatarId": "…",
  "parentHolonId":     "…"   // optional — nests inside a parent holon
}

Load Holon

GET/data/LoadHolon/{id}

Loads a single holon by its GUID. Optionally pass ?providerType=HoloOASIS to target a specific provider.

Load All Holons

GET/data/LoadAllHolons

Returns all holons across the default provider. For large datasets, use Search with filters instead.

Load Holons for Parent

GET/data/LoadHolonsForParent/{parentId}

Returns all child holons nested under the given parent holon ID.

Delete Holon

DELETE/data/DeleteHolon/{id}

Soft-deletes the holon. Pass ?hardDelete=true to permanently remove (Admin only).

Usage Visibility, Owners and Warnings

GET/api/subscription/usage/series
GET/api/subscription/app-owner/{appId}/usage
GET/api/subscription/usage/alerts

Daily usage series for charts (your own, an app pool's for its owners, anyone's for administrators), usage warnings at thresholds you choose (default 80% and 100%, optionally by email) and app owner views that show only the apps you own. Nothing shows request content. The node defaults are in OASIS.UsageVisibility in OASIS_DNA.json; each person and each app account can opt in or out for themselves and their choice wins. App pay-as-you-go lets an owner consent to a monthly cap: extra requests above the pool allowance keep working up to the cap and are billed once a month to the Stripe account of the person who turned it on (it also needs a price for the plan). People can see an estimate of their own pay-as-you-go charges (so far and projected to month end) at GET /api/subscription/usage/estimate. See the Subscription API reference for all endpoints and keys.

Holon Access Log

GET/api/data/holon-access-log/{id}
GET/api/data/access-log?avatarId={id}

Who READ a holon (ids only, never content), newest first, paged with limit and offset. Opt-in and off by default: set OASIS.AccessLog.Enabled in OASIS_DNA.json. The per-holon query is for the holon's owner or a Wizard; the avatar query returns your own reads (a Wizard may pass any avatarId). Entries hold the reader, app id, operation, holon type, holon ids (capped) and total count.

Reads are queued and written in the background, so they never slow a request, but events can be lost if the queue is full or the node stops. Volume grows with traffic; use RetentionDays (default 365) and the app, type and operation filters. Reads that bypass the WEB4 Data API (direct provider or database access) are not recorded.

Holon Audit Trail

GET/api/data/holon-audit-trail/{id}
POST/api/data/holon-audit-trail/{id}

A readable history of a holon built from its saved versions, newest first. Each entry has the version, timestamp, avatarId, avatarName (blank if not readable), an action (created, updated, deleted or restored) and changes of {field, oldValue, newValue} covering core fields and metadata keys. Long values are clipped, and JSON lists of records with an id are summarised as added/removed/changed. Query: fromVersion, toVersion, limit (max 200), offset. The POST accepts fieldLabels and skipKeys.

Only callers who may read the holon get its trail, limited to the fields they can read. Versions are assigned by the server and archived append-only with SHA-256 checksums; a soft delete keeps every version, while a permanent delete removes the holon and its history. PIPER uses this endpoint for its audit record of authority.

Save Multiple Holons

POST/data/SaveHolons

Batch-saves an array of holons in a single request. Body: { "holons": […], "providerType": "…" }. Returns an array of saved holons with their assigned IDs.

💡
OApp data storage pattern

Store each OApp's game objects, levels, and player state as holons with a shared parentHolonId representing the OApp itself. This makes it trivial to load all data for a given OApp and to migrate it between providers via HyperDrive.