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

ParameterTypeRequiredDescription
idInteger-compatibleYesPositive 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

ResponseCondition
{"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. Missing meta.tags returns 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