hot.dev/microsoft-onedrive / ::microsoft::onedrive::items

driveItems: get by id or path, list children, search, recent and shared-with-me, create folders, update, rename, move, copy (async, with a monitor URL), delete to the recycle bin, permanently delete, and restore.

Every function takes opts: drive (see ::microsoft::onedrive), OData options (select, expand, top, orderby, filter) and microsoft-graph credentials.

Permissions. Reads: Files.Read (own drive) or Files.Read.All (shared and other users' files); SharePoint libraries also accept Sites.Read.All, or Sites.Selected / Files.SelectedOperations.Selected for app-only access granted per site or file. Writes: the ReadWrite variants.

Values

DEFAULT_PAGE_SIZE

DEFAULT_PAGE_SIZE: Int 200

Functions

build-copy

fn (dest-parent-id: Str, opts: Map): Map

The copy body (pure): parentReference {driveId?, id}, name, childrenOnly, includeAllVersionHistory; unset options are omitted.

build-folder

fn (name: Str, conflict: Str): Map

The body for creating a folder (pure): {name, folder: {}, @microsoft.graph.conflictBehavior}, plus opts.description.

build-move

fn (new-parent-id: Str, opts: Map): Map

The PATCH body for a move (pure): {parentReference: {id, driveId?}, name?}.

classify-copy-status

fn (response: Result): CopyStatus

Interpret a monitor-URL response (pure). 200 and 202 carry an AsyncOperationStatus body. Personal OneDrive answers a finished copy with 303 See Other. ::hot::http/request follows a 303 that has a Location (as a GET, with no Authorization), so the answer is then the new item's URL: a 401 or 403 (its API URL needs a token) or a driveItem both mean completed. A 303 without Location arrives as itself and also means completed.

copy-item

fn (item: Any, dest-parent-id: Str): Map
fn (item: Any, dest-parent-id: Str, opts: Map): Map

POST {item}/copy - start an asynchronous copy into the folder dest-parent-id (opts.drive-id for another drive, name, conflict (fail default, replace, rename; not on personal OneDrive), children-only, include-all-versions). Returns {monitor-url, status: "accepted"} at once: check progress later with copy-status(monitor-url) from a schedule or a follow-up event, never in a loop.

job ::microsoft::onedrive::items/copy-item(file-id, archive-folder-id, {name: "Q3 (archive).xlsx"})
send("copy:started", {monitor-url: job.monitor-url})

copy-status

fn (monitor-url: Str): CopyStatus
fn (monitor-url: Str, opts: Map): CopyStatus

GET a copy's monitor URL (no Authorization header: the URL is pre-authenticated) and return a CopyStatus. Call it from a schedule or event, not in a loop; the monitor URL is short-lived.

status ::microsoft::onedrive::items/copy-status(job.monitor-url)
cond {
  not(status.done) => { send("copy:pending", {monitor-url: job.monitor-url}) }
  eq(status.status, "failed") => { println(`copy failed: ${to-json(status.error)}`) }
  => { println(`copied: ${status.resource-id}`) }
}

create-folder

fn (parent: Any, name: Str): Map
fn (parent: Any, name: Str, opts: Map): Map

POST {parent}/children - create a folder. opts.conflict is "fail" (default), "rename" or "replace". Returns the folder.

folder ::microsoft::onedrive::items/create-folder("root", "Reports", {conflict: "rename"})

delete-item

fn (item: Any): Bool
fn (item: Any, opts: Map): Bool

DELETE an item: it moves to the recycle bin (restorable for 93 days on work/school, 30 days on personal). opts.if-match (eTag) makes it conditional. Returns true.

ensure-folder

fn (path: Str): Map
fn (path: Str, opts: Map): Map

Return the folder at /path (from the drive root), creating it and any missing parents. Returns the folder driveItem.

get-doc-file

fn (item: Any): ::microsoft::onedrive/DocFile
fn (item: Any, opts: Map): ::microsoft::onedrive/DocFile

get-item normalised to a ::microsoft::onedrive/DocFile.

get-item

fn (item: Any): Map
fn (item: Any, opts: Map): Map

GET an item by id, /path, "root" or Map. opts takes select, expand (e.g. "thumbnails", "permissions") and drive.

item ::microsoft::onedrive::items/get-item("/Reports/Q3.xlsx")
item.id
item.file.hashes.quickXorHash

is-copy-done

fn (status: Map): Bool

True when a CopyStatus is completed or failed.

json

fn (method: Str, path: Str, headers: Map, body: Any, opts: Map): Any

list-all-children

fn (folder: Any): Vec
fn (folder: Any, opts: Map): Vec
fn (folder: Any, opts: Map, limit: Int?): Vec

Follow @odata.nextLink and return every child of folder (a Vec of driveItems), or at most limit. Uses top: 200 unless set.

files filter(::microsoft::onedrive::items/list-all-children("root", {}, 1000), (i) { is-map(i.file) })

list-children

fn (folder: Any): Map
fn (folder: Any, opts: Map): Map

GET {folder}/children - one page of a folder's children: Graph's {value, @odata.nextLink?}. Follow @odata.nextLink with ::microsoft::graph::api/fetch-page or use list-all-children. opts takes select, expand, top (page size), orderby (e.g. "name", "lastModifiedDateTime desc"; not on every drive type) and drive.

move-item

fn (item: Any, new-parent-id: Str): Map
fn (item: Any, new-parent-id: Str, opts: Map): Map

Move an item to another folder (by id) in the same drive, optionally renaming it (opts.name). Moving across drives is not supported by PATCH: use copy-item then delete-item. Returns the item.

permanent-delete

fn (item: Any): Bool
fn (item: Any, opts: Map): Bool

POST {item}/permanentDelete - delete without the recycle bin (OneDrive for work or school and SharePoint only). Cannot be undone. Returns true.

recent

fn (): Vec
fn (opts: Map): Vec

GET /me/drive/recent - items the signed-in user used recently (delegated only; entries from other drives carry remoteItem). Deprecated by Microsoft: degraded until November 2026, after which it returns no data. Prefer delta sync or search.

rename-item

fn (item: Any, new-name: Str): Map
fn (item: Any, new-name: Str, opts: Map): Map

Rename an item. Returns the item.

resolve-remote

fn (item: Map): Map
fn (item: Map, opts: Map): Map

For a shared item (remoteItem), fetch the target item from its own drive; otherwise return item. One hop.

restore-item

fn (item: Any): Map
fn (item: Any, opts: Map): Map

POST {item}/restore - restore a deleted item from the recycle bin (personal OneDrive only). opts.parent-id restores into another folder and opts.name renames. Returns the restored item.

search

fn (query: Str): Vec
fn (query: Str, opts: Map): Vec
fn (query: Str, opts: Map, limit: Int?): Vec

Search a drive for query (file names, metadata and content), all pages or at most limit. Defaults to {drive}/root/search(...); opts.folder searches under one folder, and opts.scope: "drive" uses {drive}/search(...), which on /me/drive also includes items shared with the user. opts also takes select, top.

hits ::microsoft::onedrive::items/search("quarterly report", {}, 25)

search-function

fn (query: Str): Str

The OData function segment for a search (pure): search(q='...') with ' doubled and the text percent-encoded.

shared-with-me

fn (): Vec
fn (opts: Map): Vec

GET /me/drive/sharedWithMe - items shared with the signed-in user (delegated only; each has a remoteItem pointing at the owner's drive). opts.allow-external: true includes other tenants' items. Deprecated by Microsoft: degraded until November 2026, after which it returns no data.

update-item

fn (item: Any, fields: Map): Map
fn (item: Any, fields: Map, opts: Map): Map

PATCH an item's metadata (name, description, parentReference, fileSystemInfo, ...). opts.if-match (an eTag) makes it conditional (412 when changed). Returns the item.

with-query

fn (path: Str, opts: Map): Str

Types

CopyStatus

CopyStatus type {
    status: Str,
    percent: Any?,
    resource-id: Str?,
    error: Map?,
    done: Bool
}

A copy job's status from its monitor URL.

• status - notStarted, inProgress, completed, failed, waiting, deletePending, cancelPending, cancelled, or unknown
• percent - percentageComplete (0..100), when reported
• resource-id - the new item's id once completed (null when Graph redirected to it instead; then list the destination folder)
• error - Graph's error object for failed
• done - true for completed and failed