Fieldmotion API Getting started

Files

Set file tags

POST /a/File_setTags

Store newline-delimited tag text in a file’s JSON metadata.

When to use this endpoint

Use File_setTags from the tag cell editor. The API treats tags as one opaque string rather than an array.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session and establish the tenant database context.

The handler performs no record-owner or resource-specific permission check. CRM screens may hide the action, but callers with tenant API/session access can target any matching file ID.

Parameters

ParameterTypeRequiredDescription
idInteger-compatibleYesPositive file ID.
valStringYesTag text, normally one tag per line. Empty string removes the meta.tags key.

Example request

$result = FM_api('File_setTags', ['id' => '4821', 'val' => "annual service\ncompressor"]);

Example response

{
  "ok": 1
}

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 non-positive.
{"error":"missing or invalid parameter: val"}The value key is absent.
{"error":"file not found"}The ID does not identify a live file.

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

Behaviour and edge cases

  • A nonblank value is stored at meta.tags; blank removes the key. Malformed legacy metadata is normalized to an empty object first. The endpoint does not update last_edited or audit changes.

See it in Fieldmotion

CRM1

Click a Tags cell on a legacy Files table and edit the newline-separated text.

CRM2

Click Tags on modern Customer, Job, User, Asset, or Asset Type file tables.

Related endpoints