Locations

Manage geographic locations for nodes

The Locations API allows you to manage geographic or logical groupings for your nodes. Locations help organize nodes by datacenter, region, or any other grouping that makes sense for your deployment.

List Locations

cURL

curl "https://panel.example.com/api/application/locations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Retrieves a paginated list of all locations on the Panel.

Query Parameters

per_page · integer · default: "50"

Number of results per page

filter[short] · string

Filter locations by short identifier

filter[long] · string

Filter locations by description

sort · string

Sort by field. Available: id. Prefix with - for descending order

include · string

Include related resources. Available: nodes, servers

Response

object · string

Always list

data · array

Array of location objects

Show Location Object

id · integer

Internal location ID

short · string

Short identifier code (1-60 characters)

long · string | null

Full description of the location

created_at · string

ISO 8601 timestamp of creation

updated_at · string

ISO 8601 timestamp of last update

{
  "object": "list",
  "data": [
    {
      "object": "location",
      "attributes": {
        "id": 1,
        "short": "us-west",
        "long": "United States - West Coast",
        "updated_at": "2024-01-01T00:00:00+00:00",
        "created_at": "2024-01-01T00:00:00+00:00"
      }
    },
    {
      "object": "location",
      "attributes": {
        "id": 2,
        "short": "eu-central",
        "long": "Europe - Central",
        "updated_at": "2024-01-15T00:00:00+00:00",
        "created_at": "2024-01-15T00:00:00+00:00"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

Get Location Details

cURL

curl "https://panel.example.com/api/application/locations/{location_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Retrieves details for a specific location.

Path Parameters

location_id · integer · required

The internal ID of the location

Query Parameters

include · string

Include related resources. Available: nodes, servers

Response

{
  "object": "location",
  "attributes": {
    "id": 1,
    "short": "us-west",
    "long": "United States - West Coast",
    "updated_at": "2024-01-01T00:00:00+00:00",
    "created_at": "2024-01-01T00:00:00+00:00"
  }
}

Create Location

cURL

curl -X POST "https://panel.example.com/api/application/locations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "short": "us-east",
    "long": "United States - East Coast"
  }'

Creates a new location on the Panel.

Request Body

short · string · required

Short identifier code for the location (1-60 characters, must be unique)

long · string

Full description of the location (optional, max 191 characters)

Response

Returns the created location object with HTTP status 201 Created.

{
  "object": "location",
  "attributes": {
    "id": 3,
    "short": "us-east",
    "long": "United States - East Coast",
    "updated_at": "2024-03-04T00:00:00+00:00",
    "created_at": "2024-03-04T00:00:00+00:00"
  },
  "meta": {
    "resource": "https://panel.example.com/api/application/locations/3"
  }
}

Update Location

cURL

curl -X PATCH "https://panel.example.com/api/application/locations/{location_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "short": "us-east-1",
    "long": "United States - East Coast (Primary)"
  }'

Updates an existing location.

Path Parameters

location_id · integer · required

The internal ID of the location to update

Request Body

All fields are optional. Only include fields you want to update.

short · string

New short identifier code (must be unique)

long · string

New description

Response

Returns the updated location object.

{
  "object": "location",
  "attributes": {
    "id": 3,
    "short": "us-east-1",
    "long": "United States - East Coast (Primary)",
    "updated_at": "2024-03-04T12:00:00+00:00",
    "created_at": "2024-03-04T00:00:00+00:00"
  }
}

Delete Location

cURL

curl -X DELETE "https://panel.example.com/api/application/locations/{location_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Deletes a location from the Panel. The location must not have any nodes assigned to it.

Path Parameters

location_id · integer · required

The internal ID of the location to delete

Response

Returns HTTP status 204 No Content on successful deletion.

A location cannot be deleted if it has any nodes assigned to it. Reassign or delete the nodes first.

Usage Examples

Creating a Multi-Region Setup

# Create locations for different regions
curl -X POST "https://panel.example.com/api/application/locations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"short": "us-west", "long": "United States - West"}'

curl -X POST "https://panel.example.com/api/application/locations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"short": "eu-central", "long": "Europe - Central"}'

curl -X POST "https://panel.example.com/api/application/locations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"short": "ap-south", "long": "Asia Pacific - South"}'

Listing Locations with Nodes

curl "https://panel.example.com/api/application/locations?include=nodes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"