Cookie Jar (cookie-jar)

Category: data | Form: | Symbol: Cj

Durable store for browser cookies, attachable to one browser at a time

Holds cookies outside any single browser element so auth state survives browser rebuilds and can be handed between browsers. Follows Chrome’s cookie shape (name/value/domain/path/secure/httpOnly/sameSite/expirationDate). A jar attaches to at most one browser at a time via spec.attached_browser_id; the attached browser can copy its live spec.cookies into the jar (browser/ops/save-cookies-to-jar) or seed its session from the jar (browser/ops/load-cookies-from-jar). Jar-side ops (import/export/list/clear/set/delete/diff/stats/prune) are for humans or agents managing the jar outside a browser session. On circles with encryption_mode=‘platform’, spec.cookies is encrypted at rest like any other spec field. Not the same thing as the cookie_jar JSON-blob parameter on platform capture-cookies ops — that’s a raw serialization format, this is a first-class element.

Guide

Durable store for browser cookies, attachable to one browser at a time

What It Does

Cookie Jar is a data element that holds browser cookies outside any single browser element, so authenticated session state survives browser rebuilds and can be handed between browsers. It stores cookie records in Chrome’s cookies-API shape (name / value / domain / path / secure / httpOnly / sameSite / expirationDate) in spec.cookies, mirroring a browser element’s own spec.cookies so an attached browser can round-trip its session state without transformation.

A jar binds to at most one browser at a time via spec.attached_browser_id. The attach / detach ops maintain that single canonical edge and enforce the single-browser invariant; the attached browser can copy its live cookies into the jar or seed its session from the jar (via the browser element’s own save-cookies-to-jar / load-cookies-from-jar ops). The jar-side ops below — import / export / list / clear / set / delete / diff / describe / prune — are for humans or agents managing the jar outside a browser session.

Every mutating op bumps spec.cookies_version (a monotonic counter) and recomputes the derived fields cookie_count, domains, and cookies_updated_at. The jar is bounded at 10 000 cookies. Because it holds live session credentials (including httpOnly cookies and auth tokens), it is visible to collaborators only and is excluded from public GitHub-mirror pushes. On circles with encryption_mode='platform', spec.cookies is encrypted at rest like any other spec field.

Element Definition

Property	Value
Type	cookie-jar
Category	data
Form	atom
Symbol	Cj
Icon	cookie / #8B4513
Storage backend	postgres
Allowed visibility	collaborator

Properties

Field	Type	Default	Description
cookies	array	[]	Cookie records (Chrome cookies-API shape). Each item requires name, value, domain; accepts extra fields verbatim. Bounded at 10 000 entries. Not panel-editable — managed by ops and browser sync.
cookies_updated_at	string (date-time)	""	UTC timestamp of the last durable cookie write; drives the freshness indicator.
cookies_version	integer	0	Monotonic counter, bumped on every mutation. Starts at 0, only increments, never wraps.
cookie_count	integer	0	Count of cookies currently in the jar. Derived — recomputed on every mutation.
domains	array	[]	Distinct domains present in the jar, sorted. Derived on every mutation.
attached_browser_id	string	""	UUID of the one browser currently attached to this jar. Empty when unattached. Maintained by attach / detach.

Cookie record fields: name (≤256 chars), value (≤8192 chars), domain (≤253 chars), path, secure, httpOnly, sameSite (lax / strict / no_restriction / none), expirationDate (Unix epoch seconds; null/absent = session cookie), storeId.

States

State	Meaning
empty	No cookies (initial state).
populated	Jar holds cookies.
orphaned	Attached browser disappeared but the jar still has cookies.

Capabilities

Capability	Description
cookie-storage	Durable store for Chrome-shape browser cookies outside any single browser session; survives browser rebuilds.
single-browser-attachment	Binds 1:1 to one browser at a time via spec.attached_browser_id; attach/detach enforce missing-browser, browser-already-attached, and jar-already-attached invariants.
merge-import	Bulk import with mode=replace (full overwrite) or mode=merge (upsert by name+domain+path); rejects imports past 10 000 cookies.
domain-scoped-ops	export, clear, and list support optional domain suffix filtering to operate on one site’s cookies.
optimistic-concurrency	spec.cookies_version is a monotonic counter; save-cookies-to-jar callers can pass expected_version to get JAR_VERSION_CONFLICT on stale writes.
expiry-management	prune drops expired cookies; describe reports expired_count and the expiration range without decrypting the full cookies array.

Error Codes

Code	Class	Retryable	Description
JAR_ALREADY_ATTACHED	conflict	No	Jar is already attached to a different browser — detach that browser first; error body includes the current attached_browser_id.
JAR_BROWSER_NOT_FOUND	not_found	No	Attach target browser_id does not resolve to a browser element in this circle.
JAR_BROWSER_MISSING	not_found	No	Jar’s attached_browser_id points to a browser that no longer exists; pass force=true to detach anyway.
JAR_BROWSER_ALREADY_ATTACHED	conflict	No	Attach target browser is already claimed by a different jar — detach that jar first.
JAR_VERSION_CONFLICT	conflict	No	save-cookies-to-jar supplied an expected_version that does not match the jar’s current cookies_version.
JAR_CAPACITY_EXCEEDED	limit	No	Import would push the jar past the 10 000 cookie limit — prune expired cookies or split into multiple jars.

Operations

All paths are relative to /api/{circle}/{slug}/ops/.

import — bulk-replace or merge cookies

POST .../ops/import · auth: write

Accepts an array of Chrome-shape cookie records. mode=replace overwrites the entire jar; mode=merge (default) keeps existing cookies and upserts incoming ones by the (name, domain, path) triplet. Bumps cookies_version, stamps cookies_updated_at. Rejects imports past 10 000 cookies with JAR_CAPACITY_EXCEEDED. Returns cookie_count, cookies_version, cookies_updated_at, added, replaced.

export — return cookies, optionally domain-filtered

POST .../ops/export · auth: read

Returns the cookies array in Chrome shape — the same format an attached browser round-trips. Filtered by domain when domain is passed (suffix match: linkedin.com matches both .linkedin.com and www.linkedin.com). Pass include_expired=false to drop cookies whose expirationDate is in the past (default true). Returns cookies, cookie_count, cookies_version.

list — UI-safe listing (no values by default)

GET .../ops/list · auth: read

Paginated listing for UI tables. By default returns only name / domain / path / expirationDate / flags — not cookie values — so raw auth secrets never hit the portal unless the caller passes include_values=true. Query params: domain, include_values (default false), limit (default 100, range 1–1000), offset (default 0). Returns cookies, total, offset, limit.

clear — remove all cookies (or all for a domain)

POST .../ops/clear · auth: write

Without domain, empties the jar. With domain (suffix match), removes only matching cookies. Bumps cookies_version. Does not detach the jar from its browser. Returns removed, cookie_count, cookies_version.

set — insert or update a single cookie

POST .../ops/set · auth: write

Upsert by (name, domain, path) — replaces a matching cookie or adds a new one. Requires name, value, domain (path defaults to /). Bumps cookies_version. Returns the resulting cookie, replaced (bool), cookies_version.

delete — remove a single cookie

POST .../ops/delete · auth: write

Deletes exactly the cookie whose (name, domain, path) matches. Requires name, domain (path defaults to /). Returns removed=true if found. Bumps cookies_version only if something was removed. Returns removed, cookie_count, cookies_version.

attach — bond this jar to a browser

POST .../ops/attach · auth: write

Sets spec.attached_browser_id. Requires browser_id. Fails with JAR_ALREADY_ATTACHED (includes the current browser_id) if the jar is already attached to a different browser. Idempotent when the same browser re-attaches. This is the authorization edge: the attached browser’s save/load ops only work on a jar bonded to it. Returns attached_browser_id.

detach — unbond this jar from its browser

POST .../ops/detach · auth: write

Clears spec.attached_browser_id, leaving the cookie payload intact. If the attached browser no longer exists (soft-deleted), returns JAR_BROWSER_MISSING unless force=true is passed. State may transition to orphaned when the browser disappeared but the jar still has cookies. Returns detached, previous_browser_id.

diff — non-mutating diff vs a browser or another jar

POST .../ops/diff · auth: read

Compares this jar against another source and returns what would change on a hypothetical merge. Pass exactly one of browser_id or other_jar_id. Returns top-level added / removed / changed counts plus a by_domain breakdown so UIs can render a “dirty” badge without fetching the full cookies array.

describe — non-mutating jar metadata

GET .../ops/describe · auth: read

Returns jar metadata without the cookie payload: cookie_count, cookies_version, cookies_updated_at, attached_browser_id, per-domain counts (domains), expired_count, oldest_expiration, newest_expiration. Safe to call on every dashboard refresh — no decryption of the cookies array required. (Intentionally not named stats, which is claimed by the platform-wide activity-stats op.)

prune — drop expired cookies

POST .../ops/prune · auth: write

Removes any cookie whose expirationDate is earlier than now. Session cookies (null/absent expirationDate) are untouched. Bumps cookies_version only if at least one cookie was pruned. Safe to call on a schedule. Returns pruned_count, cookie_count, cookies_version.

Quick Start

Create a jar

POST /api/{circle}/{project}/
Content-Type: application/json

{
  "element_type": "cookie-jar",
  "slug": "linkedin-session",
  "name": "LinkedIn Session"
}

Seed it with a cookie

POST /api/{circle}/linkedin-session/ops/set
Content-Type: application/json

{
  "name": "li_at",
  "value": "AQEDA...",
  "domain": ".linkedin.com",
  "path": "/",
  "secure": true,
  "httpOnly": true,
  "sameSite": "none"
}

Attach it to a browser

POST /api/{circle}/linkedin-session/ops/attach
Content-Type: application/json

{ "browser_id": "<browser-element-uuid>" }

Inspect without pulling values

GET /api/{circle}/linkedin-session/ops/describe

The attached browser then seeds or saves its session via its own load-cookies-from-jar / save-cookies-to-jar ops.

Common Mistakes

Hitting the 10 000-cookie ceiling. import and the cookie_count validation enforce a hard 10 000-cookie limit; a violating import fails with JAR_CAPACITY_EXCEEDED. A warning fires above 9 000. prune expired cookies or split across multiple jars.

Trying to attach an already-bound jar or browser. A jar already attached to a different browser returns JAR_ALREADY_ATTACHED; a browser already claimed by another jar returns JAR_BROWSER_ALREADY_ATTACHED. Detach the other side first. The same browser re-attaching is idempotent.

Detaching a jar whose browser was deleted. If attached_browser_id points to a browser that no longer exists, detach returns JAR_BROWSER_MISSING — pass force=true to clear the orphaned attachment.

Expecting list to return cookie values. list omits values by default so secrets never reach the portal. Pass include_values=true (or use export) when you actually need them.

Passing an attached_browser_id that isn’t a UUID. The spec validation requires attached_browser_id to be empty or a well-formed UUID.

Capabilities

• cookie-storage: Durable store for Chrome-shape browser cookies (name/value/domain/path/secure/httpOnly/sameSite/expirationDate) outside any single browser session; survives browser rebuilds
• single-browser-attachment: Binds 1:1 to one browser element at a time via spec.attached_browser_id; attach/detach ops enforce missing-browser, browser-already-attached, and jar-already-attached invariants
• merge-import: Bulk import with mode=replace (full overwrite) or mode=merge (upsert by name+domain+path triplet); rejects imports that would exceed 10 000 cookies
• domain-scoped-ops: export, clear, and list support optional domain suffix filtering so callers can operate on one site’s cookies without touching others
• optimistic-concurrency: spec.cookies_version is a monotonic counter; save-cookies-to-jar callers can pass expected_version to get JAR_VERSION_CONFLICT on stale writes
• expiry-management: prune drops expired cookies (expirationDate < now); describe reports expired_count and expirationDate range without decrypting the full cookies array

Properties

Property	Type	Default	Description
cookies	array	[]	Cookie records held by this jar. Schema mirrors the browser element’s spec.cookies (Chrome cookies API shape) so an attached browser can round-trip state without transformation. Bounded at 10 000 entries to cap worst-case spec-row size under at-rest encryption. Not directly editable in the panel — managed by attach/detach ops and browser sync.
cookies_updated_at	string	""	UTC timestamp of the last durable cookie write. Portal uses this for the freshness indicator (“synced 42s ago”) and agents reason about staleness without walking every cookie’s expirationDate.
cookies_version	integer	0	Monotonic counter, bumped on every mutation. Agents and UIs use it as a freshness marker when reasoning about cookie writes; runtime ops do not currently enforce an expected-version conflict check. Starts at 0, only increments, never wraps.
cookie_count	integer	0	Count of cookies currently in the jar. Derived — recomputed on every mutation — so UIs can render an activity summary without pulling the full cookies array.
domains	array	[]	Distinct domains present in the jar. Derived on every mutation, sorted. Lets the UI show “jar contains 3 domains: .linkedin.com, .hubspot.com, .github.com” without decrypting the full cookies array.
attached_browser_id	string	""	UUID of the one browser element currently attached to this jar. Empty string when unattached. The attach/detach ops maintain this field; it is the single canonical edge representing the jar ↔ browser binding. Browsers discover “their” jar by reverse lookup on this field.

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attach

Post /ops/attach | Auth: Write

Bond this jar to a browser (single-browser invariant)

Sets spec.attached_browser_id. Fails with JAR_ALREADY_ATTACHED (includes the current browser_id in the error body) if the jar is already attached to a different browser — the caller must detach that browser first. Idempotent when the same browser re-attaches. This is the authorization edge: the attached browser’s save/load ops only work on a jar that has bonded to it.

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

clear

Post /ops/clear | Auth: Write

Remove all cookies (or all cookies for a domain)

Without domain, empties the jar. With domain (suffix match), removes only cookies whose domain matches. Bumps spec.cookies_version. Does NOT detach the jar from its browser — the jar remains attached and can be re-populated with set or import or via the browser’s save-cookies-to-jar op.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Post /ops/delete | Auth: Write

Remove a single cookie by (name, domain, path)

Deletes exactly the cookie whose (name, domain, path) matches. Returns removed=true if a cookie was found, false otherwise. Bumps spec.cookies_version only if something was actually removed.

describe

Get /ops/describe | Auth: Read

Non-mutating jar metadata (no cookie payload returned)

Returns jar metadata without the cookie payload: cookie_count, cookies_version, cookies_updated_at, per-domain counts, expired count, oldest and newest expirationDate. Safe to call from activity feeds and dashboards on every refresh — no decryption of the large cookies array is required to serve it on platform-encrypted circles. NOTE: this op is intentionally NOT named stats — the platform- wide stats op is claimed by ActivityOpsExecutor (generic element health metrics: success rate, runs/day, tokens). Using a distinct name keeps element-specific metadata and platform activity stats available side-by-side without registration-order fragility.

detach

Post /ops/detach | Auth: Write

Unbond this jar from its browser

Clears spec.attached_browser_id, leaving the cookie payload intact. If the attached browser no longer exists (soft-deleted), this op returns JAR_BROWSER_MISSING unless force=true is passed — the force flag is the orphan-recovery escape. State may transition to orphaned when the browser disappeared but the jar still has cookies.

diff

Post /ops/diff | Auth: Read

Non-mutating diff vs a browser or another jar

Compares this jar against another source and returns what would change on a hypothetical merge. Pass exactly one of browser_id or other_jar_id. Results are grouped by domain with added, removed, and changed counts so UIs can render a “dirty” badge without fetching the full cookies array.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export

Post /ops/export | Auth: Write

Return cookies, optionally filtered by domain

Returns the cookies array in Chrome-shape — the same format an attached browser would round-trip. Filtered by domain when domain is passed (suffix match: passing ‘linkedin.com’ matches both ‘.linkedin.com’ and ‘www.linkedin.com’). By default, session or expired cookies (expirationDate in the past) are included; pass include_expired=false to filter them out. Live cookie values are session secrets — exporting them requires write-scope auth (auth: write), the same level that import, set, clear, and delete require. A read-scoped credential (auth: read, e.g. an audience viewer or a read-only API key) gets 403 on this op. Use ops/list (auth: read) for UI-safe metadata browsing — it does not return values unless the caller explicitly passes include_values=true. The hard redaction guard for accidental secret exposure lives in the auth level, not in this executor: Chrome-shape export with values is the documented round-trip contract for jar consumers (load-cookies-from-jar, export_bundle); do not gut it. REQ-MIGRATION-001, BUGS-2877.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

import

Post /ops/import | Auth: Write

Bulk-replace or merge the jar’s cookies

Accepts an array of Chrome-shape cookie records. mode=replace overwrites the entire jar; mode=merge keeps existing cookies and upserts the incoming ones. Merge identity is the (name, domain, path) triplet — an incoming cookie with the same triplet as an existing one replaces it; otherwise it is added. Bumps spec.cookies_version and stamps spec.cookies_updated_at. Rejects imports that would push the jar past 10 000 cookies with JAR_CAPACITY_EXCEEDED.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

list

Get /ops/list | Auth: Read

List cookies (UI-safe — no values by default)

Paginated listing for UI tables. By default, does NOT return cookie values (only name/domain/path/expirationDate/flags) so the raw auth secrets never hit the portal unless the caller explicitly opts in with include_values=true.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

prune

Post /ops/prune | Auth: Write

Drop cookies whose expirationDate is in the past

Removes any cookie whose expirationDate is earlier than now. Session cookies (null/absent expirationDate) are untouched. Bumps spec.cookies_version only if at least one cookie was pruned. Safe to call on a schedule.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

set

Post /ops/set | Auth: Write

Insert or update a single cookie

Upsert by (name, domain, path) — if a cookie with the same triplet already exists, it is replaced; otherwise it is added. Bumps spec.cookies_version. Returns the resulting cookie.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_fixtures

Post /ops/source/fixtures | Auth: Write

Dry-run or apply approved Source seed fixtures

Scans .triform/fixtures/ manifests from the addressed data element Source repo. Defaults to dry_run=true and never imports live runtime data. Apply requires dry_run=false plus confirm=true and dispatches approved records through existing generated element ops.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
JAR_ALREADY_ATTACHED	conflict	no	Jar is already attached to a different browser — detach that browser first; error body includes current attached_browser_id
JAR_BROWSER_NOT_FOUND	not_found	no	Attach op target browser_id does not resolve to a browser element in this circle
JAR_BROWSER_MISSING	not_found	no	Jar’s attached_browser_id points to a browser that no longer exists; pass force=true to detach anyway
JAR_BROWSER_ALREADY_ATTACHED	conflict	no	Attach op target browser is already claimed by a different jar — detach that jar first
JAR_VERSION_CONFLICT	conflict	no	save-cookies-to-jar supplied an expected_version that does not match the jar’s current cookies_version — another writer updated the jar since this caller last read it
JAR_CAPACITY_EXCEEDED	limit	no	Import would push the jar past the 10 000 cookie limit — prune expired cookies or split into multiple jars