Deep Links API

Create, manage, and customize dashboard links from your server. You don't need these to deep link: any path on your link domain already works with zero setup. Creating links through the API requires a paid plan.

Authentication

Every Deep Links endpoint requires your app's private API key (dln_priv_…) in the x-api-key header. Public SDK keys (dln_pub_…) are rejected with 401. Call these endpoints from your server only. A key acts only on the app it belongs to; links from other apps return 404. See Authentication.

Create a Deep Link

Create a new deep link with a target URL and optional customization parameters. Requires a paid plan.

POST /api/v1/deeplinks

Headers:
  x-api-key: dln_priv_your_private_key
  Content-Type: application/json

Body:
{
  "targetUrl": "https://example.com/product/123",
  "title": "Product Page Link",                    // Optional
  "subtitle": "Check out this amazing product",    // Optional
  "customPath": "summer-sale",                     // Optional
  "metadata": {                                    // Optional
    "source": "email",
    "campaign": "summer2024"
  },
  "social_title": "Amazing Product",               // Optional (max 60 chars)
  "social_description": "Best product ever",       // Optional (max 160 chars)
  "social_image": "https://cdn.example.com/og.jpg", // Optional
  "ios_button_text": "Open in App",               // Optional (max 50 chars)
  "android_button_text": "View Product",          // Optional (max 50 chars)
  "campaignId": "campaign-uuid"                   // Optional
}

Response:
{
  "id": "deeplink-uuid",
  "url_path": "summer-sale",
  "target_url": "https://example.com/product/123",
  "title": "Product Page Link",
  "created_at": "2025-01-01T00:00:00Z",
  ...
  "shortUrl": "https://yourapp.deeplinknow.com/summer-sale",
  "urlPath": "summer-sale"
}

List Deep Links

GET /api/v1/deeplinks

Headers:
  x-api-key: dln_priv_your_private_key

Query Parameters:
  campaign_id  - Filter by campaign UUID
  url_path     - Filter by URL path
  limit        - Number of results (default: 50, max: 100)
  offset       - Pagination offset (default: 0)

Response (newest first):
[
  {
    "id": "deeplink-uuid",
    "url_path": "path",
    "target_url": "https://example.com",
    "title": "Link Title",
    "last_clicked_at": null,
    ...
    "shortUrl": "https://yourapp.deeplinknow.com/path"
  }
]

Get a Deep Link

GET /api/v1/deeplinks/{id}

Headers:
  x-api-key: dln_priv_your_private_key

Response:
{
  "id": "deeplink-uuid",
  "url_path": "path",
  "target_url": "https://example.com",
  "shortUrl": "https://yourapp.deeplinknow.com/path",
  "title": "Link Title",
  "subtitle": "Link Description",
  "social_title": "Social Title",
  "social_description": "Social Description",
  "social_image": "https://cdn.example.com/og.jpg",
  "ios_button_text": "Open",
  "android_button_text": "View",
  ...
}

Update a Deep Link

PUT /api/v1/deeplinks?url_path=summer-sale

Headers:
  x-api-key: dln_priv_your_private_key
  Content-Type: application/json

Body (all fields optional):
{
  "targetUrl": "https://example.com/product/456",
  "title": "Updated Title",
  "subtitle": "Updated Description",
  "metadata": { "source": "facebook" },
  "social_title": "New Social Title",
  "social_description": "New Social Description",
  "social_image": "https://cdn.example.com/new-og.jpg",
  "ios_button_text": "Open Now",
  "android_button_text": "View Now",
  "campaignId": "new-campaign-uuid"   // or null to clear
}

Response:
{
  "id": "deeplink-uuid",
  "shortUrl": "https://yourapp.deeplinknow.com/summer-sale",
  ...
}

Update Deep Link Customization

Update only the customization fields (title, subtitle, button text, social metadata) for a deep link. Content fields require a paid plan; social fields require a paid plan unless the link already has social values.

PATCH /api/v1/deeplinks/{id}

Headers:
  x-api-key: dln_priv_your_private_key
  Content-Type: application/json

Body (all fields optional):
{
  "title": "Custom Title",
  "subtitle": "Custom Subtitle",
  "ios_button_text": "Open in iOS App",
  "android_button_text": "Open in Android App",
  "social_title": "Social Share Title",
  "social_description": "Social Share Description",
  "social_image": "https://cdn.example.com/share.jpg"
}

Response:
{
  "id": "deeplink-uuid",
  "title": "Custom Title",
  "subtitle": "Custom Subtitle",
  ...
}

Delete a Deep Link

DELETE /api/v1/deeplinks?url_path=summer-sale

Headers:
  x-api-key: dln_priv_your_private_key

Response:
{ "success": true }

# Or by id:
DELETE /api/v1/deeplinks/{id}     → 204 No Content

Search Deep Links

GET /api/v1/deeplinks/search

Headers:
  x-api-key: dln_priv_your_private_key

Query Parameters:
  query      - Text to find in title, url_path or target_url
  campaignId - Filter by campaign UUID
  startDate  - ISO datetime
  endDate    - ISO datetime
  sortBy     - "created_at" | "last_clicked_at"
  sortOrder  - "asc" | "desc" (default: "desc")
  page       - Page number (default: 1)
  limit      - 1-100 (default: 20)

Response:
{
  "data": [ { "id": "deeplink-uuid", "url_path": "path", "shortUrl": "...", ... } ],
  "pagination": { "total": 42, "page": 1, "limit": 20, "totalPages": 3 }
}

Deep Link Click Counts

GET /api/v1/deeplinks/{id}/stats?start_date=...&end_date=...

Headers:
  x-api-key: dln_priv_your_private_key

Response:
{
  "total_clicks": 120,
  "unique_clicks": 98,
  "clicks_last_24h": 7,
  "clicks_last_7d": 40,
  "last_clicked_at": "2025-01-01T12:00:00Z",
  "platform_breakdown": { "ios": 60, "android": 50, "web": 10 },
  "top_countries": [],
  "recent_stats": { "clicks": 7, "unique_clicks": 6 },
  "time_range_stats": { "total_clicks": 30, "unique_clicks": 25 }  // only with a date range
}