Create a location

POST api/locations

Creates a new location. Locations are auto-generated when new nodes are created. Nodes with the same node number are auto-assigned to the same location.

Request syntax

post api/locations '{"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	Default value
`name`	String	The name of the location.	Yes	N/A
`city`	String	The city where the location is physically located.	No	`Austin`
`state`	String	The state where the location is physically located.	No	`TX`
`addressline1`	String	The first line of the physical address of the location.	No	`123 Please Update Me`
`addressline2`	String	The second line of the physical address of the location.	No	N/A
`zipcode`	String	The zip code where the location is physically located.	No	`11111`
`country`	String	The country where the location is physically located.	No	`US`
`nodes`	String	The hostnames of the nodes to associate with the location. If the nodes are already assigned to a different location, the nodes will be moved from the previous location to the new location.	No	N/A

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 name of the template used to create the location.
`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.

Errors

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

Code	Message	Cause
422	`Validation Failed: addressline1, city, state, zipcode, country provide all or none of parameters`	The `addressline1`, `city`, `state`, `zipcode`, and `country` fields must either always be present, or omitted in the request.

Examples

Example: Create a new location and associate two nodes

This example creates a new location named Test Location with a physical location and associates nodes sit0000red0 and sit0000red1 with it.

ruby api.rb <customer_code> post /api/locations '{"name":"Test Location","city":"Austin","state":"TX","addressline1":"123 Test Way","zipcode":"11111","country":"US","nodes":["sit0000red0","sit0000red1"]}'

Response

{
    "location_id": 25844,
    "name": "Test Location",
    "template_name": "test-location",
    "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": "sit0000red0",
            "keepalive": "unknown",
            "keepalive_timestamp": 1727882885,
            "last_online": "unknown",
            "hardware_type": "test hardware",
            "updated_at": "2024-10-02T15:31:00.208Z"
        },
        {
            "node_id": 120082,
            "hostname": "sit0000red1",
            "keepalive": "unknown",
            "keepalive_timestamp": 1727882885,
            "last_online": "unknown",
            "hardware_type": "test hardware",
            "updated_at": "2024-10-02T15:31:00.232Z"
        }
    ]
}