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 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. 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

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

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	Key lacks required scope, or an API key was used where an SDK key is required
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 SDK keys