Download a file

getContent

GET /api/v1/shares/{share_id}/content

Scope: foldr.readRate cost: 5

Download a file

On a share with direct downloads this is a 302 to a short-lived URL on the storage itself, which carries its own authorisation (follow it without the Foldr token); ?direct=false keeps the bytes coming through Foldr. Range requests are honoured where the storage can seek; If-None-Match with the file’s etag answers 304. A native Google document (an item whose export is set) is downloaded as its export, always through Foldr: Content-Type is export.mime_type, Content-Disposition names it with export.extension (Minutes.docx), and as its length is not known until it has been sent there is no Content-Length and no ranges (Accept-Ranges: none; a Range is answered 200, whole). A Google type with no export (a Form) is 409 not-downloadable.

Request

curl "$FOLDR/api/v1/shares/$SHARE_ID/content" \
  -H "Authorization: Bearer $TOKEN"

$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.
path	query	string	No	Path of the file.
direct	query	boolean	No	false: never redirect, send the bytes through Foldr. Absent: the share’s own setting.

Responses

Status	Meaning	Body
200	The whole file. Content-Type is the file’s own type.	/: string (binary)
206	The range asked for. Content-Type is the file’s own type.	/: string (binary)
302	Download it from the Location URL.	none
304	If-None-Match named the file as it is now.	none

200 response

Header	Description
Content-Disposition	attachment, naming the file (filename*, UTF-8).
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.

206 response

Header	Description
Content-Disposition	attachment, naming the file (filename*, UTF-8).
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.

302 response

Header	Description
Location	Where to go.

304 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.

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	download-blocked insufficient-scope	One of: Download blocked (download-blocked); Insufficient scope (insufficient-scope).
404	not-found	Not found (not-found).
409	ambiguous-path approved-version-unavailable not-a-file not-downloadable storage-account-not-connected	One of: Ambiguous path (ambiguous-path); Approved version unavailable (approved-version-unavailable); Not a file (not-a-file); Not downloadable (not-downloadable); Storage account not connected (storage-account-not-connected).
429	rate-limited	Too many requests (rate-limited).
500	internal-error	Internal error (internal-error).
503	share-unavailable share-unreachable	One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable).