Get a file by storage URL · Fieldmotion API

When to use this endpoint

Use File_getByUrl for internal image/style/report workflows that retain a storage URL rather than a file ID. It is a heavy metadata-plus-content response.

Authentication and permissions

Normal requests require signed API-key authentication or a logged-in CRM session and are scoped to that tenant. In CRM2, ordinary file types additionally require view permission on pageFiles; CRM1 does not apply that page permission.

File type 10 is always denied by the shared read guard. Types 6, 8, and 16 bypass that guard’s session/page-files checks, while types 6, 7, and 9 bypass only its CRM2 page check after login. Routes that explicitly call the login guard still require login, and download routes still need a resolvable tenant context. A separately established shareable-link context may also bypass the shared read guard.

Parameters

Parameter	Type	Required	Description
`url`	String	Yes	Exact tenant-relative stored URL, for example `files/2/1042/<token>`.
`base64`	Integer-compatible	No	Exact integer `1` base64-encodes `data`; otherwise raw bytes are placed in the JSON field.

Example request

$file = FM_api('File_getByUrl', [
	'url' => 'files/2/1042/abc123',
	'base64' => '1',
]);

Example response

{
  "id": "4821",
  "filename": "asset-photo.jpg",
  "description": "",
  "notes": null,
  "owner_id": null,
  "meta": "{\"user_id\":37}",
  "type_enum": "2",
  "url": "files/2/1042/abc123",
  "filesize": "18422",
  "data": "/9j/4AAQSkZJRg...",
  "mimetype": "image/jpeg"
}

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error":"missing or invalid parameter: url"}`	URL is blank or absent.
`{"error":"no such file"}`	No non-deleted row has the exact URL.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

Raw binary is not a safe generic JSON representation. Without base64=1, arbitrary file bytes are assigned directly to a JSON response field. Use base64 for binary content.

If database data is blank, the storage library retrieves it. Reads refresh last_accessed at most once every seven days and can restore archived bytes into the database.
MIME type is derived only from the filename/URL extension, not content inspection.

See it in Fieldmotion

CRM1

CRM1 settings/styles and other legacy URL-backed assets use this route indirectly; ordinary file tables use File_get.

CRM2

Photo, Job-form, initialization, stock, and report-design widgets retrieve URL-backed images through this route.

Related endpoints

File_get streams by ID with browser headers.