Skip to main content

Folders

Overview​

Folders give documents a familiar hierarchy to browse. In FormKiQ a folder is derived from the document path: a document stored at finance/invoices/2026/invoice-1042.pdf sits in the folder finance/invoices/2026. Folders can also exist on their own, so you can create an empty structure before any documents arrive.

Use folders for browsing and for coarse access boundaries. Use attributes for anything you need to search, filter, or automate on, and store the documentId in other systems rather than a path, because paths change when documents and folders are moved.

Folders belong to a site. Every folder request takes an optional siteId.

How Folders Are Identified​

Folder operations use one of two identifiers:

IdentifierWhat it isWhere you get it
pathThe folder's full path, such as finance/invoices. URL-encode it when it is sent as a query parameter.You choose it.
indexKeyAn opaque key for one folder. Required by the move, delete, permission, and share endpoints.Returned when you create a folder and on each folder entry when you list a folder.

Treat indexKey as an opaque value. Do not build or parse it yourself.

List a Folder​

GET /folders returns the contents of one folder: its subfolders and its documents.

  • With no path or indexKey, it lists the top level of the site.
  • With path or indexKey, it lists that folder.
curl -X GET "${HTTP_API_URL}/folders?siteId=${SITE_ID}&path=finance%2Finvoices" \
-H "Authorization: ${AUTHORIZATION_TOKEN}"

Each entry in documents has a folder flag. Folder entries carry path and indexKey; document entries carry the usual document fields such as documentId, contentType, and lastModifiedDate. Results are paged; pass the returned next token to continue.

GET /folders lists one level. To find documents anywhere under a folder, or to search by folder name, use the folder index of POST /search.

Create a Folder​

POST /folders creates a folder. Missing parent folders in the path are created as well.

curl -X POST "${HTTP_API_URL}/folders?siteId=${SITE_ID}" \
-H "Authorization: ${AUTHORIZATION_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"path": "finance/invoices/2026"}'

The response includes the indexKey of the new folder. You do not have to create a folder before adding documents to it: adding a document with a path creates the folders in that path.

Move a Folder​

POST /folders/{indexKey}/moves moves a folder, and everything in it, to a new path.

curl -X POST "${HTTP_API_URL}/folders/${FOLDER_INDEX_KEY}/moves?siteId=${SITE_ID}" \
-H "Authorization: ${AUTHORIZATION_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"path": "archive/finance/invoices/2026"}'

A move is asynchronous. The API returns 201 as soon as the request is accepted, and the documents are moved in the background. Until the move finishes, some documents are still listed under the old path. Document IDs do not change.

To move a single document, use the MOVE document action.

Delete a Folder​

DELETE /folders/{indexKey} deletes a folder. The folder must be empty; move or delete its contents first. Deleting a folder that does not exist returns 404.

Folder Permissions​

Site-level roles decide what a user can do across a whole site. Folder permissions narrow that for one folder.

A folder permission entry names a role (a group) and the permissions that role keeps in the folder: READ, WRITE, and DELETE.

curl -X PUT "${HTTP_API_URL}/folders/permissions?siteId=${SITE_ID}" \
-H "Authorization: ${AUTHORIZATION_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"path": "finance/invoices",
"roles": [
{"roleName": "Finance", "permissions": ["READ", "WRITE", "DELETE"]},
{"roleName": "Managers", "permissions": ["READ"]}
]
}'

How a request is evaluated:

  1. The caller must first hold the site-level permission for the operation. Folder permissions never grant more than the site allows.
  2. If the folder has no permission entries, there is no further restriction.
  3. If the folder has entries, the caller must belong to a listed role whose entry includes the permission being used.
  4. Site administrators and users with governance permission for the site are not restricted by folder entries.

Because of rule 3, adding the first entry to a folder also affects every role you did not list. Decide the full set of roles that need the folder before you set permissions, then test with a member of each group.

v1.19.2 access checks

Folder permissions restrict document content access. They do not make all document metadata private: a user with site-level read access can still retrieve a document's metadata by ID with GET /documents/{documentId}, even when its content and download URL are denied. Use separate sites when metadata must also be isolated.

FormKiQ Web v4.3.8's folder permissions dialog says unlisted roles inherit their defaults. For folders with permission entries, content access instead requires a matching listed role, as described above. Test with a non-administrator account.

PUT /folders/permissions replaces the folder's entries with the list you send. Read the current entries with GET /folders/{indexKey}/permissions. Both endpoints require the GOVERN_DOCUMENT_FOLDERS permission.

In FormKiQ Web, the same setting is the Folder Permissions action on a folder. See Working with Documents.

Folder Shares​

A folder share gives a group access to one folder with READ, WRITE, or DELETE permission, without giving the group a role across the whole site. Folder shares are part of the commercial platform.

OperationEndpoint
Share a folder with a groupPOST /shares/folders/{indexKey}
List the shares available to the callerGET /shares
Remove a shareDELETE /shares/{shareKey}

Creating a share returns a shareKey. Pass it as the shareKey query parameter on GET /folders, POST /folders, and DELETE /folders/{indexKey} to act on the shared folder.

For a full walkthrough, see Folder Permissions and Sharing.

Best Practices​

  • Keep paths stable and shallow. Deep, frequently renamed structures are hard to secure and slow to move. FormKiQ Web limits new folders to 10 levels.
  • Do not encode metadata only in the path. A customer number or status belongs in an attribute, where it can be searched and validated.
  • Set permissions at a few well-chosen folders. Many small overrides are difficult to audit.
  • Plan large moves. A folder move runs in the background. Avoid starting other changes under the same path until it completes.
  • Use sites for hard separation. If two groups must never see each other's documents, separate sites are a stronger boundary than folder permissions.

Troubleshooting​

ProblemLikely causeWhat to check
A folder cannot be deletedIt still contains documents or subfolders.List the folder and empty it first.
Users lost access after permissions were setTheir role is not in the folder's entries.Add an entry for each role that needs the folder.
A user can open a folder they should notThe user is a site administrator or has governance permission, or the folder has no entries.Check the user's site permissions and GET /folders/{indexKey}/permissions.
Documents still appear under the old path after a moveThe move is still running.Wait and list again.
403 when setting permissionsThe caller lacks GOVERN_DOCUMENT_FOLDERS.Use a token with governance permission for the site.

API Reference​