Docs/API Reference

REST API Reference

Complete documentation for the Wee-Kit SDK API. Create deep links and handle attribution from your server.

Authentication

The Wee-Kit API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard under App Settings.

Important: Keep your API Secret secure. Never expose it in client-side code or public repositories.

Required Headers

Header	Description
`X-API-Key`	Your public API key (starts with `dk_live_` or `dk_test_`)
`X-API-Secret`	Your secret API key (starts with `sk_live_` or `sk_test_`)
`Content-Type`	`application/json` for all POST requests

curl -X POST https://api.wee-kit.app/api/v1/sdk/links \
  -H "X-API-Key: dk_live_your_api_key" \
  -H "X-API-Secret: sk_live_your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Link", "deepPath": "/products/123"}'

Base URL

All API requests should be made to:

https://api.wee-kit.app/api/v1

Errors

The API uses standard HTTP status codes to indicate success or failure.

Status	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API Key
`403`	Forbidden - Invalid API Secret
`409`	Conflict - Resource already exists (e.g., duplicate shortCode)
`500`	Internal Server Error

Error Response Format

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "details": [
    { "field": "deepPath", "message": "Deep path must start with /" }
  ]
}

POST

/sdk/links

Create a new deep link. Call this from your backend server when you need to generate a shareable link.

Request Body

Parameter	Type	Required	Description
`title`	string	Yes	Link title for display and analytics (1-100 chars)
`deepPath`	string	Yes	In-app path to navigate to, must start with `/` (max 2000 chars)
`shortCode`	string	No	Custom short code for URL (3-50 chars, lowercase, numbers, hyphens). Auto-generated if not provided
`customData`	object	No	Key-value pairs to pass to your app (productId, userId, etc.)
`utmParams`	object	No	UTM parameters: source, medium, campaign, term, content (each max 100 chars)
`fallbacks`	object	No	Override default fallback URLs (usually not needed - uses App Settings)
`expiresAt`	string	No	ISO 8601 expiration date (e.g., `2026-12-31T23:59:59Z`)

Example Request (all parameters)

curl -X POST https://api.wee-kit.app/api/v1/sdk/links \
  -H "X-API-Key: dk_live_your_api_key" \
  -H "X-API-Secret: sk_live_your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer Sale - Product 123",
    "deepPath": "/products/123",
    "shortCode": "summer-sale-123",
    "customData": {
      "productId": "123",
      "discount": "20%",
      "referrer": "email_campaign",
      "userId": "user_456"
    },
    "utmParams": {
      "source": "email",
      "medium": "newsletter",
      "campaign": "summer_sale_2026",
      "term": "promo",
      "content": "hero_button"
    },
    "fallbacks": {
      "ios": {
        "type": "appStore",
        "url": "https://apps.apple.com/app/id123456789"
      },
      "android": {
        "type": "playStore",
        "url": "https://play.google.com/store/apps/details?id=com.yourapp"
      }
    },
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Response

201 Created

{
  "id": "65a1b2c3d4e5f6g7h8i9j0k2",
  "appId": "65a1b2c3d4e5f6g7h8i9j0k1",
  "shortCode": "summer-sale-123",
  "fullUrl": "https://links.yourapp.com/summer-sale-123",
  "title": "Summer Sale - Product 123",
  "deepPath": "/products/123",
  "status": "active",
  "settings": {
    "fallbacks": {
      "ios": {
        "type": "appStore",
        "url": "https://apps.apple.com/app/id123456789"
      },
      "android": {
        "type": "playStore",
        "url": "https://play.google.com/store/apps/details?id=com.yourapp"
      }
    },
    "utmParams": {
      "source": "email",
      "medium": "newsletter",
      "campaign": "summer_sale_2026",
      "term": "promo",
      "content": "hero_button"
    },
    "customData": {
      "productId": "123",
      "discount": "20%",
      "referrer": "email_campaign",
      "userId": "user_456"
    },
    "expiresAt": "2026-12-31T23:59:59.000Z"
  },
  "createdAt": "2026-03-11T10:30:00.000Z",
  "updatedAt": "2026-03-11T10:30:00.000Z"
}

POST

/sdk/attribution

Check for deferred deep link attribution. Call this when your app launches to get the link data for users who installed via a deep link.

Request Body

Parameter	Type	Required	Description
`bundleId`	string	Yes	App bundle identifier (max 255 chars)
`sdkVersion`	string	Yes	SDK version string (max 20 chars)
`fingerprint`	object	Yes	Device fingerprint for matching
`fingerprint.ipHash`	string	Yes	Hashed IP address
`fingerprint.userAgent`	string	Yes	User agent string (max 1000 chars)
`fingerprint.language`	string	Yes	Device language code (max 20 chars)
`fingerprint.screenWidth`	number	No	Screen width in pixels
`fingerprint.screenHeight`	number	No	Screen height in pixels
`fingerprint.timezone`	string	No	Timezone identifier (max 50 chars)
`deviceId`	string	No	Unique device identifier (max 100 chars)
`debug`	boolean	No	Return debug information (candidates, scores)

Example Request (all parameters)

curl -X POST https://api.wee-kit.app/api/v1/sdk/attribution \
  -H "X-API-Key: dk_live_your_api_key" \
  -H "X-API-Secret: sk_live_your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "bundleId": "com.yourapp.ios",
    "sdkVersion": "1.0.0",
    "deviceId": "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
    "debug": false,
    "fingerprint": {
      "ipHash": "a1b2c3d4e5f6g7h8i9j0",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15",
      "language": "en",
      "screenWidth": 390,
      "screenHeight": 844,
      "timezone": "America/New_York"
    }
  }'

Response (Match Found)

200 OK

{
  "matched": true,
  "link": {
    "deepPath": "/products/123",
    "title": "Summer Sale",
    "shortCode": "abc123",
    "customData": {
      "productId": "123",
      "discount": "20%"
    },
    "utmParams": {
      "source": "email",
      "medium": "newsletter",
      "campaign": "summer_sale"
    }
  },
  "matchConfidence": 0.95,
  "clickTimestamp": "2026-03-11T10:25:00.000Z",
  "timeToAttribution": 300
}

Response (No Match)

200 OK

{
  "matched": false
}

POST

/sdk/install

Track app installation. Call this on first app launch to register the device and get SDK configuration.

Request Body

Parameter	Type	Required	Description
`deviceId`	string	Yes	Unique device identifier (max 255 chars)
`platform`	string	Yes	`ios` or `android`
`bundleId`	string	Yes	App bundle identifier (max 255 chars)
`sdkVersion`	string	Yes	SDK version string (max 20 chars)
`osVersion`	string	No	OS version (max 50 chars)
`deviceModel`	string	No	Device model name (max 100 chars)
`appVersion`	string	No	Your app version (max 50 chars)

Example Request (all parameters)

curl -X POST https://api.wee-kit.app/api/v1/sdk/install \
  -H "X-API-Key: dk_live_your_api_key" \
  -H "X-API-Secret: sk_live_your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
    "platform": "ios",
    "bundleId": "com.yourapp.ios",
    "sdkVersion": "1.0.0",
    "osVersion": "17.0",
    "deviceModel": "iPhone 15 Pro",
    "appVersion": "2.1.0"
  }'

Response

200 OK

{
  "success": true,
  "isNewInstall": true,
  "config": {
    "enabled": true,
    "plan": "pro",
    "features": {
      "deepLinks": true,
      "deferredDeepLinks": true,
      "analytics": true
    }
  }
}