# GET /api/v2/drive-folders/{drive_folder}

Read a drive folder

- MCP id: drive-folders.show
- Scope: api:read:project_drive
- Scope: api:read:customer_drive
- Scope: api:read:organization_drive
- Scope: api:read:user_drive
- Permission: project_drive::access
- Rate cost: 1 unit, read bucket.
- Cache-Control: private, no-store

Returns one drive folder in the detail view.

`access` is the calling user's own effective access level on it. `owner` and `parent_folder` render as references until named in include; an organisation-owned folder's owner is always a bare reference. The folder's contents are two other reads: `data.links.drive_items` for its items, and `GET /api/v2/drive-folders?filter[parent_id]={id}` for its subfolders. A folder is hard-deleted, so there is no trashed parameter. The declared permission is `project_drive::access`; the other three drive prefixes apply by owner type, and the per-folder rule is what actually decides.

## Parameters
- drive_folder (integer, path): The DriveFolder's numeric id.
- view (string, optional): Which field set to render.
- X-Request-Id (header, optional): A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.
- If-None-Match (header, optional): The ETag a read is conditional on. A match is answered 304 with no body.

## Response 200
- 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.

## Errors
- 403 forbidden-by-policy | insufficient-permission | insufficient-token-scope: Forbidden.
- 304 : Not modified.
- 400 idempotency-key-required | invalid-cursor | invalid-query-parameter | malformed-request | unsupported-parameter: Bad request.
- 401 token-expired | unauthenticated: Unauthenticated.
- 404 endpoint-not-found | resource-not-found: Not found.
- 406 not-acceptable: Not acceptable.
- 429 rate-limit-exceeded: Too many requests.
- 500 internal-error: Server error.
- 503 tenant-unavailable: Service unavailable.

## Example
```bash
curl -G \
  'https://<your-url>/api/v2/drive-folders/1' \
  --data-urlencode 'include=owner,parent_folder' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'
```