# DriveFolder

A folder in a drive: the tree plnnrly's file browser draws under a project, a customer, the organisation drive or a user's personal drive. A folder holds drive items and other folders, and it is where the drive's access rules are anchored: an item or a subfolder that inherits permissions takes them from the nearest ancestor folder that does not.

## Used by
- GET /api/v2/drive-folders: List drive folders (DriveFolderList)
- POST /api/v2/drive-folders: Create a drive folder (DriveFolder)
- GET /api/v2/drive-folders/{drive_folder}: Read a drive folder (DriveFolder)
- PATCH /api/v2/drive-folders/{drive_folder}: Update a drive folder (DriveFolder)

## DriveFolder fields
- id (integer, required): Unique identifier.
- name (string ≤ 255, required): Folder name as shown in the drive tree.
- parent_id (integer or null, required): Folder this one sits in, or `null` at the drive root.
- parent_folder (Ref or DriveFolderSummary or null, required): The folder this one sits in; absent for folders at the drive root.
- owner_type (string, required): The kind of record `owner` points at; it says which branch of `owner` applies.
- owner_id (integer, required): The id of the record `owner` points at.
- owner (Ref or ProjectSummary or CustomerSummary or UserSummary, required): The project, customer, organisation or user whose drive this folder lives in. An organisation-owned folder renders as a bare {"id": N} reference.
- order (integer, required, server-assigned): Sort position within the drive and level, as shown in the drive tree. Positions count per drive and level, so the sequence is only meaningful once the collection is narrowed to one drive and one level. It is not assigned on create, so a folder created through the API stays at 0 until it is positioned in plnnrly; reordering is not exposed in v2.0.
- created_by (integer or null, required, server-assigned): Author; always the authenticated user at create time. Null on legacy rows and where the author has since been deleted.
- inherits_permissions (boolean, required): Whether this folder takes its permissions from its parent.
- general_access (string, required): Baseline sharing tier, consulted only while `inherits_permissions` is `false`.
- access (string or null, required): The calling user's effective access level on this folder, after the permission for the owner type, the access inherited from folders and any per-folder grant.
- created_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Creation timestamp.
- updated_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Last-write timestamp; use for incremental sync.
- drive_items_count (integer ≥ 0, required): Live drive items directly in this folder that the caller may see. Archived items are not counted, and neither are items in subfolders.
- links (DriveFolderLinks, required)
  - self (url, required): The canonical URI of this record.
  - drive_items (url, required): Drive items directly in this folder.

## Variants

### DriveFolderList

What a collection returns, and what `?view=summary` returns on a single record.

16 fields.
Identical to the detail object above.

### DriveFolderSummary

The embedded form: what you get when another resource carries this one and you did not `include` it.

2 fields.
Omits: parent_id, parent_folder, owner_type, owner_id, owner, order, created_by, inherits_permissions, general_access, access, created_at, updated_at, drive_items_count, links

### DriveFolderLinks

The `links` object on this resource.

Keys: self, drive_items

## Polymorphic fields
- owner: discriminated on `owner_type`

## Example
```json
{
  "id": 1,
  "name": "Kick-off",
  "parent_id": 1,
  "parent_folder": null,
  "owner_type": "project",
  "owner_id": 1,
  "owner": {
    "id": 1
  },
  "order": 1,
  "created_by": 1,
  "inherits_permissions": false,
  "general_access": "everyone_edit",
  "access": "view",
  "created_at": "2026-03-04T09:15:00Z",
  "updated_at": "2026-03-04T09:15:00Z",
  "drive_items_count": 1,
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "drive_items": "https://<your-url>/api/v2/work-items/1"
  }
}
```