Update a location

PUT api/locations/template_name

Updates an existing location, specified by the template_name of the location.

The template_name for a location is the location name in all lowercase, replacing any spaces or special characters with hyphens, for example, a location named Location 1234 would have a template_name of location-1234. The location template_name is also in the response of the List all locations API. For more information, see List all locations.

Request syntax

put api/locations/<template_name> '{"name":"<string>","city":"<string>","state":"<string>","addressline1":"<string>","zipcode":"<string>","country":"<string>","nodes":["<string>","<string>"]}'

Request parameters

The request accepts the following data in JSON format.

Parameter	Type	Description	Required
`name`	String	The name of the location.	No
`city`	String	The city where the location is physically located.	No
`state`	String	The state where the location is physically located.	No
`addressline1`	String	The first line of the physical address of the location.	No
`addressline2`	String	The second line of the physical address of the location.	No
`zipcode`	String	The zip code where the location is physically located.	No
`country`	String	The country where the location is physically located.	No
`nodes`	String	The hostnames of the nodes to associate with the location. Any nodes previously associated with the location are removed.	No

When updating the nodes associated with a location, the updated nodes list will overwrite the old nodes list. This means that the location will be associated with only the nodes in the request. Nodes previously associated with the location will be moved to the Unassigned location.

Response syntax

{
    "location_id": integer,
    "name": "string",
    "template_name": "string",
    "addressline1": "string",
    "addressline2": "string",
    "city": "string",
    "state": "string",
    "zipcode": "string",
    "country": "string",
    "updated_at": "timestamp",
    "nodes": [
        {
            "node_id": integer,
            "hostname": "string",
            "keepalive": "string",
            "keepalive_timestamp": timestamp,
            "last_online": "timestamp",
            "hardware_type": "string",
            "updated_at": "timestamp"
        }
    ]
}

Response parameters

If the action is successful, an HTTP 200 response is returned. The following data is returned in JSON format.

Field	Type	Description
`location_id`	Integer	The ID of the location.
`name`	String	The name of the location.
`template_name`	String	The template name for the location. If a different value for `name` was specified in the request, the template name is updated to reflect the new location name.
`addressline1`	String	The first line of the physical address specified in the request. If the value wasn't in the request, the default value is returned.
`addressline2`	String	The second line of the physical address specified in the request. If the value wasn't in the request, the default value is returned.
`city`	String	The city specified in the request. If the value wasn't in the request, the default value is returned.
`state`	String	The state specified in the request. If the value wasn't in the request, the default value is returned.
`zipcode`	String	The zip code specified in the request. If the value wasn't in the request, the default value is returned.
`country`	String	The country specified in the request. If the value wasn't in the request, the default value is returned.
`updated_at`	Timestamp	The timestamp indicating when the location was last updated.
`nodes`	Array of Objects	The details of the nodes associated with the location. The `nodes` value in the request overwrites the list of nodes associated with the location.

Errors

The following are errors returned by this API. For a complete list of common errors, see Common errors.

Code	Message	Cause
-	-	-

Examples

Example: Update a location and associate two different nodes

This example updates a location with template name test-location with a new name, address, and associates nodes sit0001red0 and sit0002red1. Specifying the nodes parameter overwrites any existing nodes associated with the location. You should double check that your request includes the hostnames of all nodes to associate with the location and not just new nodes.

ruby api.rb <customer_code> put /api/locations/test-location '{"name":"Test Location 2","addressline1":"123 Test Way","zipcode":"11111","nodes":["sit0001red0","sit0001red1"]}'

Response

{
    "location_id": 25844,
    "name": "Test Location 2",
    "template_name": "test-location_2",
    "addressline1": "123 Test Way",
    "addressline2": null,
    "city": "Austin",
    "state": "TX",
    "zipcode": "11111",
    "country": "US",
    "updated_at": "2024-10-02T15:31:00.243Z",
    "nodes": [
        {
            "node_id": 120081,
            "hostname": "sit0001red0",
            "keepalive": "unknown",
            "keepalive_timestamp": 1727882885,
            "last_online": "unknown",
            "hardware_type": "test hardware",
            "updated_at": "2024-10-02T15:31:00.208Z"
        },
        {
            "node_id": 120082,
            "hostname": "sit0001red1",
            "keepalive": "unknown",
            "keepalive_timestamp": 1727882885,
            "last_online": "unknown",
            "hardware_type": "test hardware",
            "updated_at": "2024-10-02T15:31:00.232Z"
        }
    ]
}