API Endpoints

This page documents the core Linkr API endpoints. All endpoints use the base URL https://api.linkr.network/v1.

Hotspots

List Nearby Hotspots

Find hotspots near a geographic location.

/hotspots/nearby

Query Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude (-90 to 90)
`lng`	number	Yes	Longitude (-180 to 180)
`radius`	number	No	Search radius in meters (default: 1000, max: 10000)
`status`	string	No	Filter by status: `online`, `offline`, `all` (default: `online`)
`limit`	number	No	Maximum results (default: 20, max: 100)

Example Request

curl "https://api.linkr.network/v1/hotspots/nearby?lat=40.7128&lng=-74.0060&radius=500" \
  -H "Authorization: Bearer lnkr_sk_live_xxxxxxxxxxxx"

Example Response

{
  "data": [
    {
      "id": "hs_7xk2m9p4",
      "name": "Downtown Coffee",
      "type": "business",
      "location": {
        "lat": 40.7131,
        "lng": -74.0055,
        "address": "123 Main St, New York, NY 10001"
      },
      "distance_m": 47,
      "status": "online",
      "coverage_radius_m": 100,
      "signal_quality": "good",
      "performance_tier": "enhanced",
      "current_load": 3,
      "uptime_30d": 0.987
    },
    {
      "id": "hs_a3f2b7c9",
      "name": "Park Side Hotspot",
      "type": "public",
      "location": {
        "lat": 40.7125,
        "lng": -74.0072,
        "address": "City Park, New York, NY 10001"
      },
      "distance_m": 134,
      "status": "online",
      "coverage_radius_m": 150,
      "signal_quality": "excellent",
      "performance_tier": "premium",
      "current_load": 7,
      "uptime_30d": 0.999
    }
  ],
  "meta": {
    "request_id": "req_abc123def456",
    "timestamp": "2024-01-15T14:32:00Z"
  }
}

Create Hotspot

/hotspots

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name (3-50 characters)
`type`	string	Yes	`home`, `business`, or `public`
`location`	object	Yes	Location details
`location.lat`	number	Yes	Latitude
`location.lng`	number	Yes	Longitude
`location.address`	string	No	Street address
`device`	object	Yes	Device information
`device.ssid`	string	Yes	Network name
`device.mac_address`	string	Yes	Device MAC address
`settings`	object	No	Optional configuration

Example Request

curl -X POST "https://api.linkr.network/v1/hotspots" \
  -H "Authorization: Bearer lnkr_sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Home Hotspot",
    "type": "home",
    "location": {
      "lat": 40.7128,
      "lng": -74.0060,
      "address": "456 Elm St, New York, NY 10002"
    },
    "device": {
      "ssid": "Linkr-Home",
      "mac_address": "AA:BB:CC:DD:EE:FF"
    },
    "settings": {
      "max_connections": 10,
      "bandwidth_limit_mbps": 25
    }
  }'

Example Response

{
  "data": {
    "id": "hs_n3w1d789",
    "name": "My Home Hotspot",
    "type": "home",
    "status": "pending",
    "location": {
      "lat": 40.7128,
      "lng": -74.0060,
      "address": "456 Elm St, New York, NY 10002",
      "verified": false
    },
    "device": {
      "ssid": "Linkr-Home",
      "mac_address": "AA:BB:CC:DD:EE:FF",
      "linked": false
    },
    "settings": {
      "max_connections": 10,
      "bandwidth_limit_mbps": 25
    },
    "created_at": "2024-01-15T14:32:00Z"
  },
  "meta": {
    "request_id": "req_xyz789abc123",
    "timestamp": "2024-01-15T14:32:00Z"
  }
}

Newly created hotspots have status: pending until location is verified and the device is linked.

Get Hotspot

Retrieve details for a specific hotspot.

/hotspots/{id}

Path Parameters

Parameter	Type	Description
`id`	string	Hotspot ID (e.g., `hs_7xk2m9p4`)

Example Request

curl "https://api.linkr.network/v1/hotspots/hs_7xk2m9p4" \
  -H "Authorization: Bearer lnkr_sk_live_xxxxxxxxxxxx"

Example Response

{
  "data": {
    "id": "hs_7xk2m9p4",
    "name": "Downtown Coffee",
    "type": "business",
    "status": "online",
    "location": {
      "lat": 40.7131,
      "lng": -74.0055,
      "address": "123 Main St, New York, NY 10001",
      "verified": true,
      "verified_at": "2023-11-01T10:00:00Z"
    },
    "device": {
      "ssid": "Linkr-Downtown",
      "mac_address": "11:22:33:44:55:66",
      "linked": true,
      "linked_at": "2023-11-01T10:05:00Z"
    },
    "settings": {
      "max_connections": 20,
      "bandwidth_limit_mbps": 50,
      "operating_hours": null
    },
    "metrics": {
      "uptime_30d": 0.987,
      "connections_24h": 47,
      "bandwidth_used_24h_gb": 12.3,
      "performance_tier": "enhanced"
    },
    "operator_id": "usr_a3f2b7c9",
    "created_at": "2023-11-01T09:45:00Z",
    "updated_at": "2024-01-15T14:00:00Z"
  },
  "meta": {
    "request_id": "req_get456hot789",
    "timestamp": "2024-01-15T14:32:00Z"
  }
}

Update Hotspot

Modify hotspot settings. Only the hotspot’s operator can update it.

/hotspots/{id}

Path Parameters

Parameter	Type	Description
`id`	string	Hotspot ID

Request Body

Include only the fields you want to update:

Field	Type	Description
`name`	string	Display name
`settings.max_connections`	number	Maximum simultaneous users
`settings.bandwidth_limit_mbps`	number	Bandwidth cap
`settings.operating_hours`	object	Operating schedule

Example Request

curl -X PATCH "https://api.linkr.network/v1/hotspots/hs_7xk2m9p4" \
  -H "Authorization: Bearer lnkr_sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "max_connections": 30,
      "bandwidth_limit_mbps": 75
    }
  }'

Example Response

{
  "data": {
    "id": "hs_7xk2m9p4",
    "name": "Downtown Coffee",
    "settings": {
      "max_connections": 30,
      "bandwidth_limit_mbps": 75,
      "operating_hours": null
    },
    "updated_at": "2024-01-15T14:35:00Z"
  },
  "meta": {
    "request_id": "req_upd123hot456",
    "timestamp": "2024-01-15T14:35:00Z"
  }
}

Rewards

Get User Rewards

Retrieve rewards summary for a user. Requires rewards:read scope.

/users/{id}/rewards

Path Parameters

Parameter	Type	Description
`id`	string	User ID, or `me` for authenticated user

Query Parameters

Parameter	Type	Required	Description
`period`	string	No	Time period: `current`, `last`, `all` (default: `current`)

Example Request

curl "https://api.linkr.network/v1/users/me/rewards?period=current" \
  -H "Authorization: Bearer lnkr_sk_live_xxxxxxxxxxxx"

Example Response

{
  "data": {
    "user_id": "usr_a3f2b7c9",
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z",
      "status": "in_progress"
    },
    "summary": {
      "total_earned": 1247.50,
      "pending": 423.80,
      "settled": 823.70
    },
    "breakdown": {
      "availability": 748.50,
      "performance": 312.25,
      "utilization": 186.75
    },
    "hotspots": [
      {
        "hotspot_id": "hs_7xk2m9p4",
        "name": "Downtown Coffee",
        "earned": 847.30,
        "availability_score": 0.987,
        "performance_tier": "enhanced"
      },
      {
        "hotspot_id": "hs_x9y8z7w6",
        "name": "Uptown Hub",
        "earned": 400.20,
        "availability_score": 0.952,
        "performance_tier": "standard"
      }
    ]
  },
  "meta": {
    "request_id": "req_rew789usr123",
    "timestamp": "2024-01-15T14:32:00Z"
  }
}

Get Rewards History

Retrieve historical rewards data.

/users/{id}/rewards/history

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	No	Start date (ISO 8601)
`end_date`	string	No	End date (ISO 8601)
`page`	number	No	Page number
`per_page`	number	No	Results per page

Example Request

curl "https://api.linkr.network/v1/users/me/rewards/history?start_date=2023-01-01&end_date=2023-12-31" \
  -H "Authorization: Bearer lnkr_sk_live_xxxxxxxxxxxx"

Example Response

{
  "data": [
    {
      "period": "2023-12",
      "total_earned": 1523.40,
      "hotspot_count": 2,
      "avg_availability": 0.978
    },
    {
      "period": "2023-11",
      "total_earned": 1412.80,
      "hotspot_count": 2,
      "avg_availability": 0.965
    }
  ],
  "meta": {
    "request_id": "req_hist456789",
    "timestamp": "2024-01-15T14:32:00Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 12,
    "total": 12,
    "total_pages": 1
  }
}

Coverage

Get Coverage for Area

Retrieve coverage data for a geographic bounding box.

/coverage

Query Parameters

Parameter	Type	Required	Description
`north`	number	Yes	North bound latitude
`south`	number	Yes	South bound latitude
`east`	number	Yes	East bound longitude
`west`	number	Yes	West bound longitude
`zoom`	number	No	Map zoom level (affects aggregation)

Example Request

curl "https://api.linkr.network/v1/coverage?north=40.75&south=40.70&east=-73.95&west=-74.05" \
  -H "Authorization: Bearer lnkr_sk_live_xxxxxxxxxxxx"

Example Response

{
  "data": {
    "bounds": {
      "north": 40.75,
      "south": 40.70,
      "east": -73.95,
      "west": -74.05
    },
    "hotspot_count": 23,
    "coverage_area_km2": 4.7,
    "coverage_percentage": 0.68,
    "hotspots": [
      {
        "id": "hs_7xk2m9p4",
        "lat": 40.7131,
        "lng": -74.0055,
        "radius_m": 100,
        "status": "online"
      }
    ]
  },
  "meta": {
    "request_id": "req_cov123area456",
    "timestamp": "2024-01-15T14:32:00Z"
  }
}

Error Codes

Common error codes you may encounter:

Code	HTTP Status	Description
`invalid_request`	400	Request parameters are invalid
`missing_parameter`	400	Required parameter is missing
`unauthorized`	401	Invalid or missing authentication
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource doesn’t exist
`conflict`	409	Resource already exists
`rate_limit_exceeded`	429	Too many requests
`internal_error`	500	Server error (contact support)

API

API Endpoints

API Endpoints

Hotspots

List Nearby Hotspots

Query Parameters

Example Request

Example Response

Create Hotspot

Request Body

Example Request

Example Response

Get Hotspot

Path Parameters

Example Request

Example Response

Update Hotspot

Path Parameters

Request Body

Example Request

Example Response

Rewards

Get User Rewards

Path Parameters

Query Parameters

Example Request

Example Response

Get Rewards History

Query Parameters

Example Request

Example Response

Coverage

Get Coverage for Area

Query Parameters

Example Request

Example Response

Error Codes

Next Steps

API Overview

Create a Hotspot

API

​API Endpoints

​Hotspots

​List Nearby Hotspots

​Query Parameters

​Example Request

​Example Response

​Create Hotspot

​Request Body

​Example Request

​Example Response

​Get Hotspot

​Path Parameters

​Example Request

​Example Response

​Update Hotspot

​Path Parameters

​Request Body

​Example Request

​Example Response

​Rewards

​Get User Rewards

​Path Parameters

​Query Parameters

​Example Request

​Example Response

​Get Rewards History

​Query Parameters

​Example Request

​Example Response

​Coverage

​Get Coverage for Area

​Query Parameters

​Example Request

​Example Response

​Error Codes

​Next Steps

API Overview

Create a Hotspot

API Endpoints

Hotspots

List Nearby Hotspots

Query Parameters

Example Request

Example Response

Create Hotspot

Request Body

Example Request

Example Response

Get Hotspot

Path Parameters

Example Request

Example Response

Update Hotspot

Path Parameters

Request Body

Example Request

Example Response

Rewards

Get User Rewards

Path Parameters

Query Parameters

Example Request

Example Response

Get Rewards History

Query Parameters

Example Request

Example Response

Coverage

Get Coverage for Area

Query Parameters

Example Request

Example Response

Error Codes

Next Steps