Fieldmotion API Getting started

Assets

Set an asset URL

POST /a/Asset_setUrl

Replace the URL value nested at <code>meta.main.url</code> on one asset.

When to use this endpoint

Use Asset_setUrl for the dedicated URL field in the CRM1 asset editor.

The value is stored as opaque text. The endpoint does not validate URL syntax, scheme, reachability, or safety.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesPositive server-side asset ID. The handler does not verify that the row exists.
valMixedNoReplacement value; omission defaults to a blank string. Normal callers send text, but the handler does not enforce a scalar type before JSON encoding metadata.

Example request

$result = FM_api('Asset_setUrl', [
	'id' => '4821',
	'val' => 'https://assets.example.test/compressors/CMP-004',
]);

Example response

{
  "ok": 1,
  "meta": {
    "custom": [],
    "main": {
      "url": "https://assets.example.test/compressors/CMP-004"
    }
  }
}

The response returns the complete decoded metadata value after assignment, not only the URL. Existing metadata keys are preserved when the stored JSON decodes to an array.

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 does not convert to a positive integer.

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

Behaviour and edge cases

  • Missing, invalid, or JSON null metadata is replaced with {"main":[],"custom":[]} before the URL is assigned.
  • Valid scalar JSON is not normalized and can cause a PHP runtime error when the handler indexes main.
  • There is no no-change shortcut, URL validation, or deleted-state filter.
  • This is a single-record mutation; it provides no list filtering or pagination.

Side effects

  • Attempts to replace the complete encoded meta column, updates last_edited, sets edited_uuid to Asset_setUrl, invalidates the asset cache, and writes an asset audit entry.

See it in Fieldmotion

CRM1

Open an asset edit page or the editor in a customer’s Assets tab, change URL, and filter Network requests for Asset_setUrl.

CRM2

No direct production CRM2 call to Asset_setUrl was found; CRM2 uses its broader update contract.

Related endpoints