Skip to main content

Create Location

POST/api/v1/admin/proxy/locations
note

This endpoint requires Admin API Key authentication via the X-Admin-Key header.

warning

Save the agent_api_key returned in the response! It's needed to authenticate the SpiderHub agent and cannot be retrieved later.

Request Body​

location_codestringrequired

Short unique code (e.g., "ua-odesa-1", "us-nyc-1")

location_namestringrequired

Human-readable name (e.g., "SpiderHub Odesa")

country_codestringrequired

ISO 3166-1 alpha-2 country code (e.g., "UA", "US")

max_modemsintegerdefault: 20

Maximum number of modems this location can support

wireguard_ipstring

WireGuard VPN IP address for this location (e.g., "10.100.0.2")

Response​

location_idstring

UUID of the created location

location_codestring

The location code you specified

agent_api_keystring

IMPORTANT: Save this key! Used by SpiderHub agent for authentication.

Request Example

curl -X POST "https://spideriq.ai/api/v1/admin/proxy/locations" \
  -H "X-Admin-Key: your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "location_code": "ua-odesa-1",
    "location_name": "SpiderHub Odesa",
    "country_code": "UA",
    "max_modems": 20,
    "wireguard_ip": "10.100.0.2"
  }'
import requests

response = requests.post(
    "https://spideriq.ai/api/v1/admin/proxy/locations",
    headers={
        "X-Admin-Key": "your_admin_key",
        "Content-Type": "application/json"
    },
    json={
        "location_code": "ua-odesa-1",
        "location_name": "SpiderHub Odesa",
        "country_code": "UA",
        "max_modems": 20,
        "wireguard_ip": "10.100.0.2"
    }
)
location = response.json()
print(f"Location created: {location['location_id']}")
print(f"Agent key (SAVE THIS): {location['agent_api_key']}")

Response Example

{
  "location_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location_code": "ua-odesa-1",
  "location_name": "SpiderHub Odesa",
  "country_code": "UA",
  "max_modems": 20,
  "wireguard_ip": "10.100.0.2",
  "agent_api_key": "your_generated_agent_key_save_this",
  "status": "offline",
  "created_at": "2025-01-01T10:00:00.000000",
  "updated_at": "2025-01-01T10:00:00.000000"
}

Next Steps​

After creating a location:

  1. Configure SpiderHub with the agent_api_key:

    # SpiderHub/.env
    SPIDERPROXY_API_URL=https://spideriq.ai
    SPIDERPROXY_LOCATION_CODE=ua-odesa-1
    SPIDERPROXY_AGENT_KEY=your_generated_agent_key_save_this

  2. Start SpiderHub agent - it will begin sending heartbeats and registering modems

  3. Monitor location status via the List Locations endpoint