> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grdd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Document folders

> Read, organize and share document folders through the Connect API.

Use the folder routes to browse your document library, organize folders or read the part of another company's library shared with you. For document metadata, file uploads and downloads, see the [documents reference](https://docs.grdd.dev/connect-api/content/documents.md).

## Before you call

* Use the production Connect API at `https://data.grdd.net`. Set `CONNECT_API_BASE_URL="https://data.grdd.net"` for the examples. These routes do not run on Core.
* Send a [Core-issued access token](https://docs.grdd.dev/connect-api/get-token.md) as `Authorization: Bearer <ACCESS_TOKEN>`. Owner reads and writes act on the company in your token. Use the [viewer read](#read-shared-company-folders) for another company's library.

## List folders or browse a folder tree

| Task | Method and path | `200` body |
| - | - | - |
| List your folder records | `GET /api/document-folders` | `items`, a flat array of folder records. |
| Browse your library as a tree | `GET /api/document-folders/tree` | `folders` and `documents` at the root. Each folder node has its own `folders` and `documents` arrays. |
| Read direct children of one folder | `GET /api/document-folders/{folderId}/children` | `folder`, `folders` and `documents`. The arrays contain only the folder's immediate children. |

`folderId` is a positive integer. All three reads accept these optional query parameters:

| Parameter | Value | Use |
| - | - | - |
| `locale` | `en`, `es`, `de` or `fr` | Request a locale. |
| `force` | `true` or `false` | Use `true` to bypass the content cache. Omit it for a normal read. |
| `path` | String | Accepted by the query schema but does not filter these responses. Use the children route to select a folder. |

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](https://docs.grdd.dev/connect-api/content/api-conventions.md#lists).

```bash theme={null}
CONNECT_API_BASE_URL="https://data.grdd.net"
ACCESS_TOKEN="<ACCESS_TOKEN>"

curl --include --fail-with-body --get \
  "$CONNECT_API_BASE_URL/api/document-folders" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "locale=en"
```

### Folder record

| Field | Type | Meaning |
| - | - | - |
| `id` | Positive integer | Folder ID. Use it as `folderId`. |
| `griddid` | String | GNET ID of the owning company. |
| `name` | String | Folder name. |
| `parent` | Positive integer, object with `id`, or `null`. May be omitted. | Parent folder reference. A root folder has no parent. |
| `visibility` | String | `private`, `partners`, `gnet`, `unlisted` or `public`. |
| `sharewith` | Array or `null`. May be omitted. | Explicit sharing entries. Each entry permits `griddid` and `id` as optional, nullable strings. Use the viewer company's GNET ID in `griddid` to name a company. |
| `order_number` | Integer or `null`. May be omitted. | Stored display position. |
| `version` | Positive integer | Current version. Use this field when preparing an update, reorder or delete. |
| `createdAt`, `updatedAt` | ISO 8601 date-time strings with a time zone | Creation and last update times. |

## Create, rename, move or change visibility

Send JSON with `Content-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.

| Task | Method and path | `If-Match` | Status when complete |
| - | - | - | - |
| Create a folder | `POST /api/document-folders` | Not required | `201` |
| Rename a folder | `PATCH /api/document-folders/{folderId}/name` | Required | `200` |
| Move a folder | `PATCH /api/document-folders/{folderId}/parent` | Required | `200` |
| Change visibility or sharing | `PATCH /api/document-folders/{folderId}/visibility` | Required | `200` |

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.

| Method | JSON fields |
| - | - |
| Create | `name` and `visibility` are required. `name` must be a nonempty string after trimming. `parentId` is an optional positive integer or `null`. Omit it or send `null` to create a root folder. Optional `sharewith` is an array of sharing entries or `null`. Optional `locale` accepts `en`, `es`, `de` or `fr`. |
| Rename | `name` is required and must be a nonempty string after trimming. |
| Move | `parentId` is required. Send a positive integer for a parent in your library or `null` for the root. A folder cannot move into itself or a descendant. |
| Change visibility | `visibility` is required and takes a value from the folder record table. Optional `sharewith` replaces the explicit sharing list when supplied. Omit it to leave the list unchanged, or send `[]` to clear it. The request also accepts `null`. |

Send only the fields listed for the method. These bodies reject unknown fields.

Create a private folder at the root:

```bash theme={null}
IDEMPOTENCY_KEY="<IDEMPOTENCY_KEY>"

curl --include --fail-with-body --request POST \
  "$CONNECT_API_BASE_URL/api/document-folders" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"name":"<FOLDER_NAME>","visibility":"private"}'
```

Set the base URL and token as in the read example. Replace `<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.

| Field | Value |
| - | - |
| `folders` | Required nonempty array. Use each folder ID at most once. |
| `folders[].id` | Required positive integer. |
| `folders[].sortOrder` | Required integer. The saved position is `order_number` in the read record. |
| `folders[].version` | Required positive integer. Read each folder's current `version` before building the request. |

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

> [!WARNING]
>
> This method deletes the selected folder, its descendant folders and their documents. It does not move the contents to the root. Inspect the tree before you send the request.

`DELETE /api/document-folders/{folderId}?disposition=delete-subtree` has no body. Send `Idempotency-Key` and the selected folder's current version in `If-Match`.

| Parameter | Value |
| - | - |
| `folderId` | Required positive integer in the path. |
| `disposition` | Required query parameter. The only accepted value is `delete-subtree`. |
| `locale` | Optional query parameter. `en`, `es`, `de` or `fr`. |

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](https://docs.grdd.dev/connect-api/content/documents.md#public-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.

| Field | Meaning |
| - | - |
| `status` | `completed` or `pending`. |
| `data` | Folder record. For order, only the last folder in the request. For pending delete, the pre-delete folder snapshot. |
| `operationId` | Present when follow-up work is pending. |
| `effects` | Array of follow-up results. Each item has `name`, `status` (`completed`, `pending` or `failed`), `retryable` and an optional `problemCode`. |
| `invalidated` | Array of content types whose caches were invalidated, or an empty array. |

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](https://docs.grdd.dev/connect-api/content/api-conventions.md#resume-a-pending-operation). 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](https://docs.grdd.dev/connect-api/content/api-conventions.md#errors). The following cases are useful when working with folders:

| HTTP status and code | What to check |
| - | - |
| `400 invalid_request` or `400 invalid_json` | Check the path, query, fields, JSON syntax and header formats. |
| `401 unauthenticated` or `403 forbidden` | Check the token and your access to the operation. |
| `404 not_found` | The method could not find the folder in the acting company. For a move, check the requested parent as well. |
| `409 idempotency_conflict` | The key was used for a different request. |
| `412 version_conflict` | The problem can include `currentVersion`. Read the current folder data. For order, check every folder's version and position before submitting another change. |
| `413 payload_too_large` or `415 unsupported_media_type` | Keep JSON requests within 1 MiB and send `Content-Type: application/json`. |
| `422 domain_rejected` | Check whether a move would create a cycle. |
| `428 version_required` or `428 idempotency_key_required` | Send the required `If-Match` or `Idempotency-Key` header. |
| `503 temporarily_unavailable` or `503 stored_data_invalid` | Check the problem code and correlation ID. Do not treat a failed read as an empty library. |

## Related references

* [Document folder route list](https://docs.grdd.dev/connect-api/content/documents.md#folders) keeps the existing folder reference and related document methods.
* [Core document reads](https://docs.grdd.dev/connect-api/content/get-documents.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.