List Locations
List all locations. Public endpoint - no authentication required.
Response
Array of location objects
Country code (e.g., “US”)
[
{
"id": "loc-1",
"name": "New York",
"description": "US East Coast datacenter",
"country": "US",
"city": "New York",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"_count": {
"nodes": 3
}
},
{
"id": "loc-2",
"name": "London",
"description": "EU datacenter",
"country": "GB",
"city": "London",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"_count": {
"nodes": 2
}
}
]
Get Location
Get detailed information about a specific location.
Path Parameters
Response
Returns a detailed location object including associated nodes.
{
"id": "loc-1",
"name": "New York",
"description": "US East Coast datacenter",
"country": "US",
"city": "New York",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"nodes": [
{
"id": "node-1",
"displayName": "US East 1",
"isOnline": true,
"lastHeartbeat": "2024-01-15T12:00:00Z"
},
{
"id": "node-2",
"displayName": "US East 2",
"isOnline": true,
"lastHeartbeat": "2024-01-15T12:01:00Z"
}
]
}
Errors
Create Location
POST /api/locations
Authorization: Bearer {token}
Content-Type: application/json
Authentication
Requires admin role.
Request Body
Location name (1-100 characters)
Country code (e.g., “US”, “GB”, “DE”)
{
"name": "Tokyo",
"description": "Asia Pacific datacenter",
"country": "JP",
"city": "Tokyo"
}
Response
Returns the created location object with status 201.
{
"id": "loc-3",
"name": "Tokyo",
"description": "Asia Pacific datacenter",
"country": "JP",
"city": "Tokyo",
"createdAt": "2024-01-15T12:00:00Z",
"updatedAt": "2024-01-15T12:00:00Z"
}
Errors
Update Location
PATCH /api/locations/{id}
Authorization: Bearer {token}
Content-Type: application/json
Path Parameters
Authentication
Requires admin role.
Request Body
All fields are optional. Only include fields you want to update.
Location name (1-100 characters)
{
"description": "Updated datacenter description",
"city": "Tokyo"
}
Response
Returns the updated location object.
{
"id": "loc-3",
"name": "Tokyo",
"description": "Updated datacenter description",
"country": "JP",
"city": "Tokyo",
"createdAt": "2024-01-15T12:00:00Z",
"updatedAt": "2024-01-15T12:05:00Z"
}
Errors
400 - Validation failed404 - Location not found
Delete Location
DELETE /api/locations/{id}
Authorization: Bearer {token}
Path Parameters
Authentication
Requires admin role.
Response
Errors
400 - Location has associated nodes404 - Location not found
Usage Example
Here’s a typical workflow for setting up a new datacenter location:
# 1. Create a location
curl -X POST https://api.stellarstack.io/api/locations \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Singapore",
"description": "Southeast Asia datacenter",
"country": "SG",
"city": "Singapore"
}'
# Response: { "id": "loc-sg-1", ... }
# 2. Create a node in this location
curl -X POST https://api.stellarstack.io/api/nodes \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"displayName": "SG Node 1",
"host": "node1.sg.example.com",
"port": 8080,
"locationId": "loc-sg-1",
"memoryLimit": 34359738368,
"diskLimit": 107374182400,
"cpuLimit": 8
}'
# 3. List all locations to verify
curl https://api.stellarstack.io/api/locations