REST API reference

• Preserved: IDs, child relationships, tasks, attachments, and task statuses. Move/rename and audit commit together.
• Rejected: moving a project under another node; self/descendant/list parents; foreign workspaces; subtree depth overflow.
• Stale placement: send the original parentId as expectedParentId with a parentId mutation; mismatch returns 409. Rename-only PATCH preserves the current parent. Empty/unknown-field mutations are rejected.
• Across projects: inherited descendant lists must be valid under destination statuses. Overrides retain their own statuses and do not block a move based on project defaults.
• List to root: materializes its inherited statuses. Standalone list into project: keeps its statuses as an override. No move remaps task statuses.

Allowed icons:

diamond, briefcase, target, home, star, heart, globe, clock,
mapPin, settings, lock, users, user, folder, archive, bookmark,
list, checklist, calendar, flag, package, shoppingBag, fileText,
inbox, trash, pencil, eye, eyeOff, sparkles, code, link, comment, save

Legacy color names remain accepted:

Folder/list descriptions remain empty.

{
  "workspace": {}, "role": {}, "permissions": [],
  "members": [], "roles": [], "nodes": [], "documents": [],
  "tables": [], "documentPages": [], "fields": [],
  "projectFields": [], "listStatusConfigs": [], "listTagColorConfigs": []
}

The example shows response keys, not a complete instance response.

Other arrays are empty; the role list retains the caller’s own role. Bootstrap metadata never grants task-body, Document-body, Table-record, or export access. Management-only roles can use Settings without reading tasks.

• Queries and calculations share four global / two per-account slots and a 30-second checkpoint deadline.
• Processing uses bounded chunks; summaries use constant-sized accumulators. Authentication/permissions are rechecked between chunks and before returning.
• A changed/missing/nonmatching query anchor returns 409: refresh. Pages are not a cross-request snapshot.
• Incompatible compared source values return 422, not misleading ordering. Failed, expired, or cancelled work returns no partial totals/results; connections and slots are released.
• HEAD on summary validates access without calculating.

{
  "format": "hopya-table",
  "version": 1,
  "name": "Inventory",
  "columns": [
    {"key":"qty","name":"Quantity","type":"number","options":[]},
    {"key":"active","name":"Active","type":"checkbox","options":[]}
  ],
  "records": [
    {"qty":12.5,"active":false},
    {"qty":null,"active":null}
  ]
}

Connection POST accepts {name,dialect,host?,port?,database?,username?,password?,tls?,filename?}.

An uncertain source commit can leave an unresolved intent. Workspace export v8 includes local Table data, appearance, committed-image metadata, and safe tableSources descriptors—not connection secrets, file bytes, or remote rows. Use per-Table export for remote data.

• A schema-valid item may exceed the soft 2 MiB budget so it remains whole; an encoded stored record above 8 MiB fails rather than truncates.
• The (createdAt,id) seek avoids offset drift when an earlier item is deleted. Use a bulk stream for one consistent dataset snapshot.

{
  "nodeId": "11111111-1111-4111-8111-111111111111",
  "title": "Rehearse backup recovery",
  "description": "Verify restored attachments and membership.",
  "status": "todo",
  "priority": "high",
  "startDate": "2026-09-07",
  "dueDate": "2026-09-10",
  "tags": ["operations"],
  "assigneeId": null,
  "checklist": [{"text":"Verify task data","done":false}],
  "parentId": null,
  "customFields": {}
}

Replace illustrative IDs with real resources from your instance.

• Field PATCH returns 409 if it would invalidate any saved value, including unassigned values. Validation scans one task map at a time. Safe audit and field update commit atomically; task values/versions and assignment revisions stay unchanged.
• Field deletion uses indexed single-row value/version reads, removes assignments, and advances affected task/configuration versions. field.delete records exact touched-task count; audit failure rolls everything back.
• New formula fields require a shared expression (=0 is the browser starter). Referenced fields cannot be renamed/deleted until shared formulas are updated. Legacy definitions without settings.formula keep per-task expressions until deliberately configured.
• Raw formula strings allow ≤200 characters / 20 references. New/changed references must name exact sibling fields and cannot self-reference; quoted reference-like text is literal. Removing an input does not block unrelated edits to an unchanged formula.
• Display evaluation supports arithmetic, comparisons, quoted strings, and SUM, AVERAGE, MIN, MAX, ROUND, ABS, IF, CONCAT, with bounded nesting and no JavaScript execution. Referenced formula strings are not recursively evaluated. Raw strings survive REST/export; missing references, malformed expressions, and non-finite results display the raw expression.

• Project PATCH replaces statuses, allowing add/reorder/rename/color/completion/removal. Its removal check considers only currently inheriting lists; overridden lists do not block it. Existing request/response/concurrency shape stays intact.
• List GET returns stored configuration, not a materialized effective copy. inheritedProjectUpdatedAt is always present, even for an overridden list. List GET requires membership + items:read or structure:write.
• Supplied expectedUpdatedAt must match the list revision or return 409. When enabling an override from inheritance, missing expectedProjectUpdatedAt returns 400; mismatch returns 409. The owner is resolved inside the mutation transaction.
• Replacing an existing override/restoring inheritance needs only the list revision. A supplied project revision adds no conflict condition in those transitions. Every list has a stored row from creation/migration; first-write semantics match later writes.
• Invalidating tasks in the list returns 409. Mutation plus safe list.statuses.update audit is atomic. Workspace detail and exports carry all field-owner configurations in projectFields; standalone statuses appear in GET/detail/export.
• Legacy projects retain todo, backlog, in_progress, review, done. Migration 006/new projects use that order, with todo first and only done initially completed. Custom IDs work in page/bulk/MCP filters with unchanged cursor binding and authorization.

• Passwordless unlink returns 409 unless another identity remains for the exact configured issuer and SSO has a configured client. Inactive-issuer links are not recovery.
• Configuration must exactly match discovery issuer, not a normalized equivalent URL.
• Password-backed admins may unlink themselves, but are signed out. Matching in-flight callbacks cannot restore the removed identity/session.
• Unlink is not a permanent IdP ban: restrict JIT and/or disable the upstream identity when quarantining access.

• Draft revisions rise across saves/publications, never reset on publication. Re-read the retained draft before the next save/publish. Stale requests return 409; queued/active runs keep their immutable version.
• Before execution and each node—even read/send-only nodes—the publisher must still exist, belong to the workspace, and have items:read. Failure is closed.
• update_item acts only on triggering itemId as the publisher, not event actor/test caller. It rechecks items:read + items:write immediately before mutation; ordinary task validation applies.
• Nested causation is limited to depth five; an automation cannot re-enter its own causation chain.
• Legacy create produces a versioned linear graph and preserves {{steps.N.output}}; existing linear versions keep ordered execution under no-redirect transport. Lists mark graph versions with graph:true.
• Legacy action/steps PATCH cannot replace a graph version; graph trigger changes require draft publication. Name/enabled remain patchable; linear trigger PATCH creates a new immutable linear version.
• Migration 0002_automation_linear_compatibility preserves linear representations larger than the graph-only 256 KiB limit and repairs HTTP-body {{event}} to {{nodes.<triggerId>.output.event}} in derived linear forms. Original steps, queued runs, published graphs, credential bindings, and edited drafts survive. Graph publication retains its own limits.

• OAuth state is hash-only; verifier encrypted; refresh advances credential version. This is a generic authorization-code/PKCE client, not verified-provider certification.
• origin is exact scheme/host/optional port. pathPrefix permits only its exact path or descendants. DNS/address checks run at validation and dispatch.
• Private RFC1918/IPv6 ULA is allowed. Unspecified, loopback, link-local, IPv4 multicast/reserved (224.0.0.0/4 and above), IPv6 multicast, and mapped loopback/link-local forms are blocked.
• AUTOMATION_NETWORK_EXCEPTIONS bypass address/HTTPS blocks only for exact origins, never credential origin/path binding or redirect rejection.

id, title, description, status, priority, startDate, dueDate,
tags, assigneeEmail, nodeId, nodePath, createdAt, updatedAt