Docs, Pages, Views, and file access

Docs and Pages#

Collections and creation#

Create a Doc at the Workspace root by supplying only name. To create it at a Space, Folder, or List, also send stable location_id and matching location_type.

Single resources#

GET|PATCH|PUT|DELETE /workspaces/{ws}/docs/{docId}
GET|PATCH|PUT|DELETE /workspaces/{ws}/pages/{pageId}

doc_id, page_id, and Page doc_id are immutable. Page parents must belong to the same Doc and may not create a cycle. Deleting a Page promotes its direct children to its parent; deleting a Doc deletes its Pages.

Moving a Doc#

A Doc's location is set at creation and changed only through the dedicated move endpoint. The Doc container and every Page are relocated in one atomic transaction, and the Doc's location frontmatter field is updated to match. The request body takes the same location_id + location_type pair as Doc creation:

curl -X POST "$IT_BASE/workspaces/$IT_WS/docs/$DOC_ID/move" \
  -H "Authorization: Bearer $IT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "location_id": "LST-API", "location_type": "list" }'

location_type accepts space, folder, or list. A no-op move (same owner) returns 400 SAME_LOCATION.

Views#

A View is a saved query/layout stored exactly the way the plugin stores it: a view-*.md file in a _views directory, with a stable VW- id and a location frontmatter key (everything, or space:…/folder:…/list:…) that the plugin's Views bar matches on. Views support the same collection, single-resource, and field routes as other structured resources:

Creation needs a name; type must be one of the plugin's view types (list, table, board, calendar, gantt, timeline; defaults to list). Real plugin fields such as description, group_by, sort_by, filters, visible_fields, default, and order pass straight through to frontmatter. location_id + location_type pick the owner; with no location the View belongs to the workspace root (location: everything). view_id and location are immutable through field writes — the move endpoint relocates the file and rewrites location in one atomic transaction, exactly like the Doc move.

curl -sX POST "$IT_BASE/workspaces/$IT_WS/views" -H "Authorization: Bearer $IT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Sprint Board","type":"board","group_by":{"field":"status"},"location_id":"LST-API","location_type":"list"}'

Files and Vaults#

The following routes exist below both /workspaces/{ws} and /vaults/{ws}:

Paths are exact and root-relative. Binary application/octet-stream uploads preserve the submitted bytes. File size, Workspace quota, and inline/blob thresholds are enforced.

Managed Workspace resources#

The low-level API cannot bypass structured validation:

• reading a managed Item path through /file or /note returns sanitized public Item Markdown, including derived relationships and null in stored secret-field slots;
• such a read sets X-InventTasks-Redacted: true when secret fields exist;
• low-level PUT or DELETE of any managed Workspace source file returns 409 MANAGED_RESOURCE;
• use the stable-ID resource or field endpoint to modify it.

One deliberate exception: files whose stable id is duplicated stay writable and deletable by path. A duplicate id makes the object unaddressable through structured routes (they answer 409 DUPLICATE_ID instead of guessing), so the path route is the only tool that can repair that broken state — delete or fix the extra copy and the catalog heals.

Arbitrary Workspace files and Vault files remain writable by path. Attachment bytes are ordinary files under _attachments/<item-id>/ and stay reachable here even though the dedicated attachment routes (Items and search) are the recommended way to manage them together with their Item metadata.