API Overview

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_YOUR_API_KEY" \
  https://api.warplink.app/v1/links

API keys are created under Keys > API keys in the WarpLink dashboard. The full key is only shown once at creation time. Store it securely.

The dashboard issues two credential types and both use the wl_live_ prefix followed by 32 alphanumeric characters, so they are indistinguishable by sight. API keys carry the scopes you choose and are meant for backend scripts, CI, and AI agents. SDK keys are pre-scoped for the mobile SDKs and are the only credential that can record install attribution. An SDK key can call only the three SDK endpoints (/v1/sdk/validate, /v1/links/resolve/{slug} and /v1/attribution/match); every other endpoint answers it with 403 SDK_KEY_ROUTE_FORBIDDEN. See Authentication for the full comparison.

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, install records, and attribution attempts
keys:read	Read API key metadata
keys:write	Create and revoke API keys
domains:read	Read custom domain configuration
domains:write	Create, verify, and delete custom domains
org:read	Read organization details
org:delete	Delete an organization
team:read	Read team members and invitations
team:write	Invite, remove, and manage team members

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. attribution:write cannot be requested on an API key, so an API key on this endpoint always returns 403 FORBIDDEN.

Rate Limiting

API keys are rate limited to 60 requests per minute per key. The SDK routes (GET /v1/sdk/validate, GET /v1/links/resolve/{slug} and POST /v1/attribution/match) are limited to 60 requests per minute per key per client IP address. Devices on different IP addresses get separate allowances. Devices behind one public IP address, such as an office or carrier network, share one.

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": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "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	Key lacks required scope, or an API key was used where an SDK key is required
403	SDK_KEY_ROUTE_FORBIDDEN	An SDK key was used on an endpoint that is not an SDK endpoint. Use an API key for this request
403	PASSWORD_REQUIRED	The link is password protected and cannot be resolved
404	NOT_FOUND	Resource not found
409	SLUG_TAKEN / DUPLICATE_APP / APP_HANDLE_TAKEN	Resource already exists
409	RENAME_PERIOD_OPEN / RENAME_PERIOD_NOT_OPEN / RENAME_EXTENSION_LIMIT / CONFIRMATION_REQUIRED / LINK_MOVE_NOT_PENDING	The app or link is not in the state the request needs
410	GONE	Resource has expired
422	INVALID_DOMAIN	The domain is not allowed for the link
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, delete, and resolve 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
• Organizations: Read an organization and delete it
• Keys: Create, list, and revoke the SDK keys and API keys used to authenticate requests
• Custom Domains: Register, verify, and manage the custom domains that serve your short links
• Analytics: Query an overview, one link's detail, a filtered breakdown with period comparison, or a comparison of several links
• Exports: Start a click export for an organization or one link, poll its status, and download the CSV file
• Invitations: Invite team members by email, list pending invitations, and revoke access
• Attribution: Match an app install to the link click that drove it, using device signals, probabilistic matching, or referrers
• Installs: List every install record and every attribution attempt, matched or not, with stable IDs and match details
• SDK endpoints: Authentication endpoint used by the mobile SDKs to validate SDK keys