# DriveItem

A file or document in a drive: the rows plnnrly's file browser lists under a project, a customer, the organisation drive or a user's personal drive. A drive item is the envelope (title, folder, tags, sharing tier), and its body, where it has one, lives on the drive document it points at through `content_record`. Access is decided per item: the permission for the owner type, then the folders it inherits from, then any per-item grant.

## Used by
- GET /api/v2/drive-items: List drive items (DriveItemList)
- POST /api/v2/drive-items: Create a drive item (DriveItem)
- GET /api/v2/drive-items/{drive_item}: Read a drive item (DriveItem)
- PATCH /api/v2/drive-items/{drive_item}: Update a drive item (DriveItem)
- POST /api/v2/drive-items/{drive_item}/actions/restore: Restore an archived drive item (DriveItem)

## DriveItem fields
- id (integer, required): Unique identifier.
- title (string ≤ 255, required): Item title.
- group (string or null ≤ 255, required): Free-text grouping label shown in the drive tree.
- kind (string, required): What this item is. Everything created through the API is a `document`; the other kinds come from uploads in plnnrly.
- source (string, required): Where the item came from: `builtin` for an editor document, `upload` for a file uploaded in plnnrly.
- folder_id (integer or null, required): Folder this item sits in, or `null` at the drive root.
- drive_folder (Ref or DriveFolderSummary or null, required): The folder this item sits in; absent for items 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 item lives in. An organisation-owned item renders as a bare {"id": N} reference.
- content_record_type (string or null, required): The kind of record `content_record` points at; it says which branch of `content_record` applies.
- content_record_id (integer or null, required): The id of the record `content_record` points at.
- content_record (Ref or null, required): The body this item points at: a drive document for an editor document, `null` for an item with no body yet. Renders as a bare {"id": N} reference; read the body from `GET /api/v2/drive-documents/{drive_document}`.
- order_column (integer, required, server-assigned): Sort position, assigned by the server. Positions count per drive and folder, so the sequence is only meaningful once the collection is narrowed to one drive and one folder. 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.
- archived_by (integer or null, required, server-assigned): The user who archived this item; set on delete and cleared on restore.
- inherits_permissions (boolean, required): Whether this item takes its permissions from its folder.
- 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 item, after the permission for the owner type, the access inherited from folders and any per-item 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.
- deleted_at (timestamp (YYYY-MM-DDThh:mm:ssZ) or null, required): When this item was archived, or `null` while it is live.
- comments_count (integer ≥ 0, required): Comments on this item.
- files_count (integer ≥ 0, required): Files attached to this item, counting the attachments list in plnnrly, the single uploaded file and the images embedded in the document body.
- tags_count (integer ≥ 0, required): Tags on this item.
- links (DriveItemLinks, required)
  - self (url, required): The canonical URI of this record.
  - comments (url, required): Comments on this drive item.
  - files (url, required): Files stored on this drive item.
- tags (array of TagSummary ≤ 50, optional, only with include): Tags on this item. An item takes at most 50 tags, so the include lists them all. `tag_ids` replaces the whole set. Wrapped in `{ data, meta }`; `meta.truncated` says whether the cap was hit and `meta.count` is the full count.
  - id (integer, required): Unique identifier.
  - title (string ≤ 255, required): Tag title as shown in the UI.

## Variants

### DriveItemList

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

27 fields.
Identical to the detail object above.

### DriveItemSummary

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

5 fields.
Omits: group, kind, source, folder_id, drive_folder, content_record_type, content_record_id, content_record, order_column, created_by, archived_by, inherits_permissions, general_access, access, created_at, updated_at, deleted_at, comments_count, files_count, tags_count, tags, links
Narrows owner: Ref or ProjectSummary or CustomerSummary or UserSummary -> Ref

### DriveItemLinks

The `links` object on this resource.

Keys: self, comments, files

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

## Example
```json
{
  "id": 1,
  "title": "Kick-off notes",
  "group": "…",
  "kind": "document",
  "source": "builtin",
  "folder_id": 1,
  "drive_folder": null,
  "owner_type": "project",
  "owner_id": 1,
  "owner": {
    "id": 1
  },
  "content_record_type": "drive_document",
  "content_record_id": 1,
  "content_record": null,
  "order_column": 1,
  "created_by": 1,
  "archived_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",
  "deleted_at": "2026-03-04T09:15:00Z",
  "comments_count": 1,
  "files_count": 1,
  "tags_count": 1,
  "tags": {
    "data": [
      {
        "…": "2 fields of TagSummary"
      }
    ],
    "meta": {
      "truncated": false,
      "…": "1 optional field left out"
    }
  },
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "comments": "https://<your-url>/api/v2/work-items/1",
    "files": "https://<your-url>/api/v2/work-items/1"
  }
}
```