Folders and search

Folders organize documents. They never change a document's recipients, its validity, or the links people were emailed. Moving a document, or deleting the folder it sits in, touches nothing a signer can see.

The folder tree

• Folders belong to a workspace's team. Each has a name (up to 120 characters) and an optional parent_id; a folder with no parent is at the root.
• Names are unique among siblings: two folders at the same level cannot share a name.
• The tree is at most 5 levels deep. depth is 1 for a root folder.
• Folder ids are plain UUIDs scoped to the workspace. Another workspace's id counts as nonexistent.
• Deleting a folder moves its subfolders and documents up to its parent; deleting a root folder leaves them unfoldered. Nothing is deleted but the folder itself.

curl -s https://signenvoystaging.fly.dev/v1/folders -H "Authorization: Bearer $SENV_API_KEY"

{
  "items": [
    {"id": "8f1a...", "name": "Contracts", "parent_id": null, "depth": 1},
    {"id": "c3d9...", "name": "2026", "parent_id": "8f1a...", "depth": 2}
  ]
}

The tree comes back flat; rebuild it from parent_id and depth.

# create
curl -s -X POST https://signenvoystaging.fly.dev/v1/folders \
  -H "Authorization: Bearer $SENV_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "2026", "parent_id": "8f1a..."}'

# rename, or move under another parent (move_to_root: true moves it to the top)
curl -s -X PATCH https://signenvoystaging.fly.dev/v1/folders/c3d9... \
  -H "Authorization: Bearer $SENV_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "FY2026"}'

# delete (204): contents move up one level
curl -s -X DELETE https://signenvoystaging.fly.dev/v1/folders/c3d9... -H "Authorization: Bearer $SENV_API_KEY"

Put a document in a folder

curl -s -X PATCH https://signenvoystaging.fly.dev/v1/documents/doc_... \
  -H "Authorization: Bearer $SENV_API_KEY" -H "Content-Type: application/json" \
  -d '{"folder_id": "c3d9..."}'

# take it out again
curl -s -X PATCH https://signenvoystaging.fly.dev/v1/documents/doc_... \
  -H "Authorization: Bearer $SENV_API_KEY" -H "Content-Type: application/json" \
  -d '{"clear_folder": true}'

A null in a patch means "leave unchanged", which is why removing a document from its folder is an explicit clear_folder rather than "folder_id": null. A document is in at most one folder; new documents start unfoldered.

Every folder operation that names something the tree cannot hold (an unknown folder, a duplicate name among siblings, a move into the folder's own subtree, a sixth level) answers 422 folder-invalid with the rule in detail.

List and search

curl -s "https://signenvoystaging.fly.dev/v1/documents?folder=c3d9...&q=acme&sort=activity" \
  -H "Authorization: Bearer $SENV_API_KEY"

• folder: documents in that folder only (not its subfolders).
• q: free text, up to 200 characters. It matches the document's title, its recipients' names and email addresses, and the name of the template it was created from. Words match as prefixes; quote a phrase to match it whole.
• status, sort, limit, offset: as before; q and folder combine with them.

The template name is recorded when the document is created. Renaming the template later does not change what older documents match on, so a search for the old name still finds them.

In the dashboard, the search field sits above the documents list and each result says what matched (title, recipient, or template). The folder tree appears in the list only once the workspace has a folder; a workspace that never creates one never sees it.

From the command line

From senv 0.2.0: senv doc list --folder <id> --q acme, and senv folder list|create|rename|move|rm wrap the calls above. Until then, the API calls are the way.