Skip to main content

​
API Overview

The Linkr API allows developers to integrate coverage data, manage hotspots programmatically, and build applications on top of the Linkr network.

​
What You Can Do

The API enables:
  • Query coverage: Find hotspots near a location, check availability
  • Manage hotspots: Register, configure, and monitor hotspots programmatically
  • Access metrics: Retrieve performance data and rewards information
  • Build integrations: Create custom dashboards, monitoring tools, or location-aware apps

​
Base URL

All API requests use the following base URL: 
https://api.linkr.network/v1

​
Authentication

The API uses bearer token authentication. Include your API key in the Authorization header: 
curl -H "Authorization: Bearer lnkr_sk_live_xxxxxxxxxxxx" \
  https://api.linkr.network/v1/hotspots

​
Getting an API Key

  1. Log in to your Linkr account
  2. Navigate to Settings → API Keys
  3. Click Create New Key
  4. Choose the scopes you need
  5. Copy and securely store the key (it won’t be shown again)

​
Key Types

TypePrefixUse Case
Livelnkr_sk_live_Production access to real data
Testlnkr_sk_test_Development and testing
Keep your API keys secure. Never expose them in client-side code or public repositories. If a key is compromised, revoke it immediately.

​
Scopes

API keys can be scoped to specific operations:
ScopePermissions
hotspots:readView hotspot data
hotspots:writeCreate and modify hotspots
coverage:readQuery coverage data
rewards:readView rewards information
users:readRead user profile data

​
Request Format

​
Content Type

All requests that include a body should use JSON: 
Content-Type: application/json

​
Common Headers

HeaderRequiredDescription
AuthorizationYesBearer token authentication
Content-TypeFor POST/PUTMust be application/json
X-Request-IDNoOptional client-generated request ID for tracing

​
Response Format

All responses return JSON with a consistent structure.

​
Success Response

{
  "data": {
    // Response payload
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T14:32:00Z"
  }
}

​
List Response

Paginated lists include pagination metadata: 
{
  "data": [
    // Array of items
  ],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T14:32:00Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 143,
    "total_pages": 8
  }
}

​
Error Response

Errors include a code and human-readable message: 
{
  "error": {
    "code": "invalid_request",
    "message": "The 'lat' parameter is required",
    "details": {
      "field": "lat",
      "reason": "missing"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T14:32:00Z"
  }
}

​
HTTP Status Codes

CodeMeaning
200Success
201Created (for POST requests)
400Bad request (invalid parameters)
401Unauthorized (missing or invalid token)
403Forbidden (insufficient permissions)
404Not found
429Too many requests (rate limited)
500Internal server error

​
Rate Limiting

API requests are rate limited to ensure fair usage:
PlanLimit
Free100 requests/minute
Developer1,000 requests/minute
Business10,000 requests/minute
Rate limit headers are included in every response: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1705330320
When rate limited, you’ll receive a 429 response: 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 42 seconds.",
    "details": {
      "retry_after": 42
    }
  }
}

​
Pagination

List endpoints support pagination using page and per_page parameters: 
curl "https://api.linkr.network/v1/hotspots?page=2&per_page=50" \
  -H "Authorization: Bearer lnkr_sk_live_..."
ParameterDefaultMaximum
page1-
per_page20100

​
Versioning

The API is versioned via the URL path (/v1/). We maintain backward compatibility within a version. Breaking changes result in a new version. Current version: v1

​
SDKs and Libraries

Official SDKs are available for common languages:
  • JavaScript/TypeScript: npm install @linkr/sdk
  • Python: pip install linkr-sdk
  • Go: go get github.com/linkr-network/linkr-go

​
Webhooks

Linkr can send webhooks for real-time event notifications:
  • Hotspot status changes
  • Rewards settlements
  • Session events
Configure webhooks in Settings → Webhooks in your dashboard.

​
Testing

Use test mode API keys (lnkr_sk_test_) for development:
  • Test keys work with sandbox data
  • No effect on production hotspots or rewards
  • Same API behavior as production

​
Next Steps

Endpoints

Detailed endpoint reference

Architecture

How the system works