/v1/files/readFile/:filepathOrId
—
post
Path Parameters
FileMatcherPathParameters

Path parameters for identifying a file by either filepath or file ID

FieldTypeRequiredDescription
filepathOrIdstringNo

File path with workspace rootname (case insensitive) or file ID for flexible file identification

Example: /workspace-rootname/folder/file.ext

Request Headers
ReadFileEndpointHTTPRequestHeaders_POST

HTTP request headers for POST file read operations

FieldTypeRequiredDescription
RangestringNo

HTTP Range header specifying byte range(s) to request

Example: bytes=0-499

If-RangestringNo

HTTP If-Range header value (ETag or Last-Modified date) for conditional range requests

Example: "etag-value"

Content-TypestringYes

HTTP JSON request content type

Example: application/json

AuthorizationstringNo

Access token

Example: Bearer <token>

Request Query
ReadFileEndpointHttpQuery

Query parameters for the read file HTTP endpoint

FieldTypeRequiredDescription
wnumberNo

Resize to width if file is an image

Number subset: floating point or integer

Example: 600

hnumberNo

Resize to height if file is an image

Number subset: floating point or integer

Example: 400

posstring or numberNo

Position or gravity to use when fit is cover or contain

Gravity or strategy to use when fit is cover or contain

Enum: topright toprightright bottombottomleft bottomleftleft topnorthnortheasteastsoutheastsouthsouthwestwestnorthwestcentreentropyattention

Example: center

Position to use when fit is cover or contain

Number subset: floating point or integer

Example: 5

fitstringNo

How the image should be resized to fit provided dimensions

Enum: containcoverfillinsideoutside

Example: cover

bgstringNo

Hex background color to use when fit is contain

Example: #FFFFFF

withoutEnlargementbooleanNo

Do not enlarge if the width or height are already less than provided dimensions

Example:

formatstringNo

Format to transform image to if file is an image

Enum: jpegpngwebptiffraw

Example: webp

downloadbooleanNo

Whether the server should add "Content-Disposition: attachment" header which forces browsers to download files like HTML, JPEG, etc. which it'll otherwise open in the browser

Request Body
ReadFileEndpointParams

Parameters for reading/downloading a file with optional image processing

{
filepath?: string
fileId?: string
imageResize?: ImageResizeParams
imageFormat?: string
download?: boolean
ranges?: Array<Range>
rangeHeader?: string
ifRangeHeader?: string
}
ImageResizeParams

Parameters for resizing images on-the-fly during file retrieval

{
width?: number
height?: number
fit?: string
position?: string | number
background?: string
withoutEnlargement?: boolean
}
Range

Byte range with start and end positions

{
start: number
end: number
}
200 — Response Headers
ReadFileEndpointHTTPResponseHeaders

HTTP response headers for file read operations

FieldTypeRequiredDescription
Content-TypestringYes

Get file endpoint result content type. If request is successful, it will be the file's content type if it is known or application/octet-stream otherwise, and application/json containing errors if request fails

Example: image/jpeg

Content-LengthstringYes

HTTP response content length in bytes

Example: 1024

Content-DispositionstringNo

HTTP response content disposition

Example: attachment; filename="file.txt"

Accept-RangesstringNo

Indicates that the server supports range requests

Example: bytes

Last-ModifiedstringNo

Date and time when the file was last modified

Example: Wed, 21 Oct 2015 07:28:00 GMT

ETagstringNo

Entity tag for cache validation

Example: "a1b2c3d4e5f6789012345678901234ab"

Content-RangestringNo

Indicates where in the full body message a partial message belongs

Example: bytes 0-499/1024

200 — Response Body
binary
4XX or 5XX — Response Headers
HttpEndpointResponseHeaders_ContentType_ContentLength

FieldTypeRequiredDescription
Content-TypestringYes

HTTP JSON response content type

Example: application/json

Content-LengthstringYes

HTTP response content length in bytes

4XX or 5XX — Response Body
EndpointErrorResult

Endpoint error result

{
errors?: Array<ExternalError>
}
ExternalError

{
message: string
}