Create a folder

createFolder

POST /api/v1/shares/{share_id}/folders

Scope: files.writeRate cost: 2

Create a folder

The folder it goes in must exist; the new name follows the name rules (one name, no ”/”, no spaces at either end). Something already called that is never replaced: on_conflict “fail” answers 409, “rename” picks the first free name, so read the answer’s path. Send an Idempotency-Key: sending the same request again with the same key answers the first answer again and creates nothing more.

Request

curl -X POST "$FOLDR/api/v1/shares/$SHARE_ID/folders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"path":"string"}'

$FOLDR is your site’s address (for example https://files.example.com) and $TOKEN is an access token. See Getting access.

Parameters

Name	In	Type	Required	Description
share_id	path	string	Yes	The share’s id.
Idempotency-Key	header	string	Yes	A value of your own, 1 to 255 visible ASCII characters (a UUID, say), new for each new request. The same key with the same request within 24 hours answers the first answer again (with Idempotent-Replayed: true) and changes nothing; with a different request it is refused (422). Your app’s keys are its own, for each person.

Request body

application/json, required: CreateFolderBody

Field	Type	Description
path	string	Required. The new folder’s full path in the share, its name last: “/Reports/2027”. The folder it goes in must exist. The leading ”/” is optional.
on_conflict	string, one of fail, rename	What to do when something is already called that: “fail” (the default) answers 409 conflict; “rename” creates it under the first free name in Foldr’s style (“2027 copy”). Nothing is ever replaced.

Example:

{
  "path": "string"
}

Responses

Status	Meaning	Body
201	The folder, at its canonical path.	application/json: Item

201 response

Header	Description
ETag	The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.
Location	Where to read what was made.

Item:

Field	Type	Description
share_id	string (uuid)	Required. The id of the share the item is in.
path	string	Required. The canonical path: as the storage holds it (its case), Unicode NFC, always starting with ”/”. ”/” is the top of the share. Send this form back in later calls.
name	string	Required. The item’s name (the last segment of its path; the share’s name for the top).
kind	string, one of file, folder	Required. file or folder.
size	integer or null	Required. Size in bytes; null for a folder, and null when the item has no fixed byte size (a native Google document, exported on download: see export).
modified	string or null (date-time)	Required. Last modified (RFC 3339, UTC), where the storage reports it.
mime_type	string or null	Required. The item’s own media type, as the storage reports it or guessed from the name; null for a folder. A native Google document has Google’s own type here (application/vnd.google-apps.document for a Doc); export says what it downloads as.
export	Export or null	Required. For a native Google document that can be downloaded, what content delivers: its media type and the extension the download is named with. Null for everything else, including a native Google type that cannot be downloaded (a Form: content answers 409 not-downloadable).
etag	string or null	Required. The item’s entity tag: the storage’s own where it has one, else a weak tag over size and modified time (over modified time alone for a native Google document, whose export is made afresh each time). Null on a search hit, which comes from the index; GET …/item for the live one.
read_only	boolean	Required. True when the person cannot change things in this share.
checked_out	Checkout or null	Required. Who has the item checked out, or null. Null on a search hit.

Example:

{
  "share_id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
  "path": "string",
  "name": "string",
  "kind": "file",
  "size": 1,
  "modified": "2026-11-04T09:30:00Z",
  "mime_type": "string",
  "export": {
    "mime_type": "string",
    "extension": "string"
  },
  "etag": "string",
  "read_only": false,
  "checked_out": {
    "by": {},
    "since": "2026-11-04T09:30:00Z"
  }
}

Errors

Every error is an application/problem+json document (ProblemDetails); branch on its type or code. See Errors.

Status	Problem types	When
400	invalid-path invalid-request	One of: Invalid path (invalid-path); Invalid request (invalid-request).
401	invalid-token	Invalid token (invalid-token).
403	insufficient-scope write-not-allowed	One of: Insufficient scope (insufficient-scope); Not allowed for this app (write-not-allowed).
404	not-found	Not found (not-found).
409	ambiguous-path conflict not-a-folder storage-account-not-connected	One of: Ambiguous path (ambiguous-path); Conflict (conflict); Not a folder (not-a-folder); Storage account not connected (storage-account-not-connected).
413	too-large	Too large (too-large).
422	idempotency-key-reused	Idempotency key reused (idempotency-key-reused).
429	daily-write-limit rate-limited	One of: Daily write limit reached (daily-write-limit); Too many requests (rate-limited).
500	internal-error	Internal error (internal-error).
503	share-unavailable share-unreachable write-failed	One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).