Ask to share

createShareRequest

POST /api/v1/shares/{share_id}/share-requests

Scope: sharingRate cost: 2

Ask to share a file or folder

The request waits for an approver and is answered 202 with status pending_approval; nothing is shared until an approver agrees, and the answer never carries a link. Refused (409 no-approver) when nobody but the person could approve it, and (409 already-shared) when the person already shares the item or has a request for it waiting: an app only starts sharing. Send an Idempotency-Key: the same request sent again with it answers the first answer and asks nothing more.

Request

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

$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, new for each new request. The same key with the same request within 24 hours answers the first answer again and asks nothing more; with a different request it is refused (422).

Request body

application/json, required: ShareRequestBody

Field	Type	Description
path	string	Required. The path of the file or folder to share (an inbox needs a folder).
kind	string, one of people, public_link, secure_link, inbox	Required. people: people in the organisation; public_link: a link anyone with it can open; secure_link: a link for the outside email addresses named; inbox: an email address that files sent to it arrive in (a folder).
people	array or null	For people: their email addresses, usernames or exact group names (at most 20).
permission	string or null, one of read, write, null	For people: “read” (the default) or “write”.
recipient_emails	array or null	For secure_link: the outside email addresses it is for (at most 20).
expiry_days	integer or null	Days until access ends once approved; 0 or absent for never. For a link, -1 ends it after its first download.
message	string or null	A note shown with the link (at most 1,000 characters).

Example:

{
  "path": "string",
  "kind": "people"
}

Responses

Status	Meaning	Body
202	The request, waiting for an approver.	application/json: ShareRequest

202 response

Header	Description
Location	Where to read what was made.

ShareRequest:

Field	Type	Description
id	string (uuid)	Required. The request’s id.
share_id	string (uuid)	Required. The id of the share the item is in.
path	string	Required. The item’s canonical path.
kind	string	Required. What was asked for. Known values: people, public_link, secure_link, inbox. Clients must accept values not listed here.
status	string	Required. Where it stands: pending_approval until an approver decides; approved; declined (by an approver, or left undecided until it lapsed); withdrawn. Known values: pending_approval, approved, declined, withdrawn. Clients must accept values not listed here.
created_at	string or null (date-time)	Required. When it was asked for (RFC 3339, UTC).
decided_at	string or null (date-time)	Required. When it was decided, or null while it waits.

Example:

{
  "id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
  "share_id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
  "path": "string",
  "kind": "string",
  "status": "string",
  "created_at": "2026-11-04T09:30:00Z",
  "decided_at": "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	already-shared ambiguous-path conflict no-approver storage-account-not-connected	One of: Already shared (already-shared); Ambiguous path (ambiguous-path); Conflict (conflict); No approver (no-approver); Storage account not connected (storage-account-not-connected).
422	idempotency-key-reused validation-failed	One of: Idempotency key reused (idempotency-key-reused); Validation failed (validation-failed).
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).