This endpoint allows you to modify the metadata of an individual measurement agents.

Body fields

Field	Description	Type	Allowed values	Example	Required
agent	The data in here is the data used to select the agent to modify the metadata of	object	See below	`{"mac_address": "0E00847AD801"}`	Yes
metadata	In this blob you can specify the fields you wish to modify, available fields are listed below	object	See below	`{"package": "AcmeCorp:100x20"}`	Yes
backdate_from	You can specify a UNIX time stamp of the date from which this metadata will be applied, if not specified it will default to today. This allows you to set an agent to have changed package in the past and have this reflected in SamKnows One.	integer	UNIX timestamps not more than 28 days old	1531991804	No
overwrite_all	Specifying true here will remove any other metadata values currently specified. For example, if a package is set and you do not define a package in your request, the package will be nulled; if you are setting new custom metadata, it will overwrite any existing, rather than merging with what was already there. This defaults to false (only updating what you specify) when not specified.	boolean	`true`, `false`	false	No

Specifying agent(s) to modify

In order to specify an agent, you can specify as many different criteria as you wish and any measurement agents that match this criteria will have the modification performed. In the majority of situations where you're only modifying a single agent, we recommend using a unique key such as agent_id, unit_id, MAC address or a custom metadata field such as customer number.

If no measurement agents are applicable then you will receive a 404.

The 'standard' fields you can use are:

Field	Description	Type	Example
agent_id	The SamKnows-generated `agent_id`	string	`3c736caa-be23-4e4b-b39d-2adc4ae4ff48`
unit_id	The SamKnows-generated `unit_id`	integer	`1029617`
mac_address	The MAC address provided to SamKnows infrastructure on registration	string	`0E00847AD801`
isp	The name of an ISP, matching how it is stored in the SamKnows database	string	`AcmeCorp`
package	An ISP:Package pair to match measurement agents by	string	`AcmeCorp:100x20`
timezone	The IANA timezone an agent is located in	string	`Europe/London`
custom	Set of key-values containing custom metadata to match by. If set, must contain at least one key-value.	object	`{"country": "England", "region": "London"}`

New metadata

Any measurement agents that match will have their metadata changed to the values you specify.

The 'standard' fields you can use are:

Field	Description	Type	Example
package	An ISP:Package pair to set against the measurement agents. It is possible to specify just the Isp by just including the ISP name for example `AcmeCorp:`. In this case, the measurement agents will be set the Isp and have any existing package removed.	string	`AcmeCorp:100x20`
timezone	The IANA timezone an agent is located in	string	`Europe/London`
custom	Set of key-values containing the new custom metadata. Will merge with existing unless overwrite_all set. If set must contain at least one key-value.	object	`{"country": "England", "region": "London"}`

You can find out more about custom metadata fields including their identifiers from within SamKnows One in the

Test agents.