Before you call
- Use the production Connect API at
https://data.grdd.net. SetCONNECT_API_BASE_URL="https://data.grdd.net"for the examples. These routes do not run on Core. - Send a Core-issued access token as
Authorization: Bearer <ACCESS_TOKEN>. Owner reads and writes act on the company in your token. Use the viewer read for another company’s library.
List folders or browse a folder tree
folderId is a positive integer. All three reads accept these optional query parameters:
Send each parameter once. Unknown or duplicate parameters return
400 invalid_request. There is no client pagination parameter. Responses can include meta. If meta.partial is true, do not treat an omitted folder or document as proof that it does not exist. See partial list results.
Folder record
Create, rename, move or change visibility
Send JSON withContent-Type: application/json and an Idempotency-Key on each request. Use an 8 to 128 character printable ASCII key without spaces. Use a distinct key for each new change. Reuse a key only for the same request.
For methods that require
If-Match, read the folder’s version and send it as "v<VERSION>", with the quotes. For example, substitute your version for <VERSION>. The folder reads provide the version in the record. The create and update responses also send ETag with the new version.
Send only the fields listed for the method. These bodies reject unknown fields.
Create a private folder at the root:
<FOLDER_NAME> with a JSON-escaped folder name. A completed response returns the new folder in data. Save its id and version if you need to change it later.
Set folder order
PATCH /api/document-folders/order sets the display positions of one or more folders in your company. Send Content-Type: application/json and Idempotency-Key. This method does not use If-Match. Send each folder’s expected version in the JSON body.
A completed response is
200. Its data and ETag describe the last folder in the request, not all updated folders. Read the list again to get the other versions. The API writes each position separately. If the request fails, check the current positions and versions before sending another write.
Delete a folder and its contents
DELETE /api/document-folders/{folderId}?disposition=delete-subtree has no body. Send Idempotency-Key and the selected folder’s current version in If-Match.
A completed response is
204 with no body. A pending folder response is 202 with the deleted folder’s snapshot in data. This method works through descendants before deleting the selected folder. If a delete fails or times out, read the tree to check what remains before issuing another delete.
Read shared company folders
GET /api/document-folders/partner/{griddid} returns the folder tree you may see for the company named by griddid. Send your Bearer token. It accepts the same query parameters as the owner reads. The path name does not grant access or make the read anonymous.
The API checks visibility and sharing for each folder and document. It can return public records, GNET-visible records for signed-in companies, explicitly shared records and partners records when Core confirms the partnership. Folder visibility does not override a document’s own access rules.
The 200 body contains folders, documents and optional meta. The tree omits folder sharewith lists and uses the reduced document record. A visible item whose parent folder is absent from the returned tree appears at the root. Do not infer access to the parent from that placement.
Check write results and resume pending work
A create, rename, move, visibility or order response contains these fields. A pending delete uses the same body; a completed delete has no body.
A
202 folder body with status: "pending" means the reported folder write committed but follow-up work is incomplete. Use operationId with the existing document operation recovery method. It retries the unfinished effects, not the original write. Do not repeat the write with a new idempotency key to finish those effects.
While the idempotency record is available, repeating the same request with the same key returns the stored result. The source configures a 24-hour retention period. A repeat while the first request is running can instead return a 202 partial_success problem body. This is not a folder record or proof that the change committed. Check the operation or read the folder before deciding what to do next.
Errors
See the Connect API error format. The following cases are useful when working with folders:Related references
- Document folder route list keeps the existing folder reference and related document methods.
- Core document reads return document metadata or an individual document. They do not use the Connect folder tree contract. Keep the Core call if your integration needs its response or access rules.