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.

The WarpLink REST API manages links, apps, API keys, custom domains, and install attribution. All endpoints live under https://api.warplink.app/v1, authenticate with Bearer API keys, and share a flat rate limit of 60 requests per minute on every plan. Errors return a consistent JSON envelope.

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 wl_live_ prefix. 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. See the full rate limiting reference for backoff strategies and best practices.

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

See the full errors reference for troubleshooting guidance on each code.

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.

Endpoints

Links: Create, list, retrieve, update, and delete deep links, including destinations, fallbacks, and UTM parameters
Apps: Register and manage the mobile apps used for deep linking, including iOS and Android platform configuration
API Keys: Create, list, and revoke the keys used to authenticate API requests
Custom Domains: Register, verify, and manage the custom domains that serve your short links
Invitations: Invite team members by email, list pending invitations, and revoke access
Organizations: Retrieve and manage your organization, including plan, billing period, and usage
Attribution: Match an app install to the link click that drove it, using device signals, fingerprints, or referrers
SDK endpoints: Authentication endpoint used by the mobile SDKs to validate API keys

API Overview