Files
Get file tags
/a/File_getTags
Return the stored newline-delimited tag text for one file.
When to use this endpoint
Use File_getTags when opening the legacy tag editor. Modern tables often already receive tags inside meta.
Authentication and permissions
Use signed API-key authentication or a logged-in CRM session on the account’s routed host. File IDs and stored URLs normally resolve within that tenant; they are not public or cross-tenant identifiers. Session CSRF applies where required by the dispatcher.
The shared content-read guard denies type 10. For ordinary file types it requires a user session; CRM2 sessions (crmVersion=2) additionally need Files View (pageFiles_view). CRM1 does not receive that CRM2 page permission check.
Types 6, 8 and 16 return before the shared guard’s login/Files-page checks. Types 7 and 9 bypass the CRM2 Files-page check only after a user is established; type 6 is also treated as an app asset. An internal shareable-file context can bypass the remaining ordinary checks. Explicit route login checks still apply, and these exceptions do not override the dispatcher’s configured record-scope guard.
When department/team or Assigned Jobs Only scope is configured for the actor, the dispatcher adds record-scope checks. This is selected by account features/actor flags, separately from the CRM2-only Files View check; the existing TeamAccess entry guard has no CRM-version condition. Explicit id/ids values are checked against visible file records. Other filename-only selections or mapped-filter-only bulk mutations can be rejected for lacking an explicit scoped selection.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer-compatible | Yes | Positive file ID. Use the tenant file-record ID returned by upload/list/detail calls. This is separate from type_id/typeId (the linked resource ID), and from the random token in a storage URL. |
Example request
$tags = FM_api('File_getTags', ['id' => '4821']);
Example response
"annual service\ncompressor"
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: id"} | ID is absent or non-positive. |
{"error":"no such file"} | No row matches. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Soft-deleted rows return
no such file. Missingmeta.tagsreturns an empty string. Malformed metadata decodes as null and also falls back to empty. - There is no pagination or side effect.
Side effects
- No content read, storage hydration, mail or record mutation.
See it in Fieldmotion
CRM1
Click the Tags cell on Customer, Job, Asset, User, Task, or related Files tables.
CRM2
Most modern tables display tags from mapped metadata; some tag editors still call the matching setter directly rather than this getter.
Related endpoints
File_setTagswrites the same metadata key.- File identifiers and downloads explains file ID, resource ID, type enum, stored URL and the different content response shapes.