REST API Reference: Auth & Rate Limits

Reference for the WarpLink REST API: authentication, rate limiting, error handling, and the endpoints for links, apps, and attribution.

Base URL

All API requests use the following base URL:

https://api.warplink.app/v1

Authentication

Authenticate requests using a Bearer token in the Authorization header:

curl -H "Authorization: Bearer wl_live_xxx" \
  https://api.warplink.app/v1/links

API keys are created in the WarpLink dashboard. Keys use the prefix wl_live_ for production and wl_test_ for test environments. The full key is only shown once at creation time — store it securely.

Required Scopes

Each endpoint requires specific scopes on the API key:

Scope	Description
`links:read`	Read link data
`links:write`	Create, update, and delete links
`apps:read`	Read app configuration
`apps:write`	Create, update, and delete apps
`analytics:read`	Read click analytics

Attribution match requests (POST /v1/attribution/match) require an SDK key, not an API key. SDK keys are auto-granted links:read and attribution:write.

Rate Limiting

All API keys are rate limited to 60 requests per minute.

Rate limit headers are included on every response:

Header	Description
`X-RateLimit-Limit`	Max requests per window
`X-RateLimit-Remaining`	Requests remaining
`X-RateLimit-Reset`	Seconds until window resets

When the rate limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Error Format

All errors return a consistent JSON structure:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Link not found",
    "details": {
      "fields": [
        { "field": "destination_url", "message": "Invalid URL" }
      ]
    }
  }
}

Error Codes

HTTP Status	Code	Description
400	`VALIDATION_ERROR`	Request body or query params failed validation
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	API key lacks required scope
404	`NOT_FOUND`	Resource not found
409	`SLUG_TAKEN` / `DUPLICATE_APP`	Resource already exists
410	`GONE`	Resource has expired
429	`RATE_LIMIT_EXCEEDED`	Too many requests
500	`INTERNAL_ERROR`	Server error

Pagination

List endpoints return paginated results:

{
  "data": [...],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Use limit (1–100, default 20) and offset (default 0) query parameters to page through results.

API Overview