Quick Start Guide

Overview

The Relink API provides a powerful GraphQL-like reactive body approach for managing smartlinks programmatically. With a single endpoint, you can create, update, and manage all types of smartlinks with intelligent validation that adapts to your smartlink type.

Prerequisites

1. Subscription Requirements

API access requires a paid subscription:

✅ Professional Plan: Full API access
✅ Enterprise Plan: Full API access
❌ Starter Plan: API access restricted

2. Get Your API Key

Log in to your Relink dashboard
Navigate to Settings → API Keys
Click “Generate New API Key”
Copy your API key (format: rlk_xxxxxxxxxxxxxxxx)
Store securely - it won’t be shown again

Test Your Setup

Validate Your API Key


curl -X GET https://relink.is/api/v1/validate \
  -H "Authorization: Bearer rlk_your_api_key_here"

Expected Response:


{
  "success": true,
  "message": "API key is valid",
  "data": null,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Your First Smartlink

Create an App Smartlink

The API uses a GraphQL-like reactive body where fields adapt based on your smartlink type:


curl -X POST https://relink.is/api/v1/smartlink \
  -H "Authorization: Bearer rlk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "smartlinkName": "My First App",
      "smartlinkType": "App",
      "appStoreLink": "https://apps.apple.com/app/myapp",
      "googlePlayLink": "https://play.google.com/store/apps/details?id=myapp",
      "fallBackLink": "https://myapp.com"
    },
    "openGraph": {
      "title": "Download My App",
      "description": "The best app for productivity",
      "imageUrl": "https://myapp.com/og-image.jpg"
    }
  }'

Response:


{
  "success": true,
  "message": "Smartlink created successfully",
  "data": {
    "id": "clp123abc456def",
    "status": "Active",
    "type": "App",
    "relink": "https://relink.is/abc123",
    "configuration": {
      "smartlinkName": "My First App",
      "smartlinkUrl": "abc123",
      "smartlinkType": "App",
      "appStoreLink": "https://apps.apple.com/app/myapp",
      "googlePlayLink": "https://play.google.com/store/apps/details?id=myapp",
      "fallBackLink": "https://myapp.com"
    },
    "analytics": {
      "totalClicks": 0,
      "totalQrCodeScans": 0,
      "totalFallBack": 0
    }
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

🎉 Congratulations! Your smartlink is now live at the returned relink URL.

Exploring Different Types

URL Shortener


curl -X POST https://relink.is/api/v1/smartlink \
  -H "Authorization: Bearer rlk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "smartlinkName": "My Short URL",
      "smartlinkType": "Url"
    },
    "shortener": {
      "url": "https://very-long-url-example.com/with/many/parameters"
    }
  }'

Landing Page


curl -X POST https://relink.is/api/v1/smartlink \
  -H "Authorization: Bearer rlk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "smartlinkName": "My Landing Page",
      "smartlinkType": "Landing"
    },
    "landing": {
      "title": "Welcome!",
      "description": "Choose an action below",
      "themeColor": "#007bff"
    },
    "landingButtons": [
      {
        "title": "Visit Website",
        "link": "https://example.com"
      },
      {
        "title": "Contact Us",
        "link": "mailto:[email protected]"
      }
    ]
  }'

QR Code Page


curl -X POST https://relink.is/api/v1/smartlink \
  -H "Authorization: Bearer rlk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "smartlinkName": "Restaurant Menu",
      "smartlinkType": "QRTag"
    },
    "qrTag": {
      "title": "Our Menu",
      "description": "Scan to view our delicious offerings",
      "themeColor": "#ff6b35"
    },
    "qrTagButtons": [
      {
        "title": "View Menu",
        "link": "https://restaurant.com/menu",
        "preset": "restaurant"
      },
      {
        "title": "Call Us",
        "link": "tel:+1234567890",
        "preset": "phone"
      }
    ]
  }'

Managing Your Smartlinks

Get All Smartlinks


curl -X GET https://relink.is/api/v1/smartlink \
  -H "Authorization: Bearer rlk_your_api_key_here"

Update Smartlinks (Partial Updates)

The API supports GraphQL-like partial updates. Only specify the fields you want to change:


# Update only the app store link
curl -X PATCH https://relink.is/api/v1/smartlink \
  -H "Authorization: Bearer rlk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "clp123abc456def",
    "configuration": {
      "appStoreLink": "https://apps.apple.com/app/updated-link"
    }
  }'


# Update only Open Graph data
curl -X PATCH https://relink.is/api/v1/smartlink \
  -H "Authorization: Bearer rlk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "clp123abc456def",
    "openGraph": {
      "title": "Updated Title",
      "description": "Updated description"
    }
  }'

Get Analytics


curl -X GET "https://relink.is/api/v1/smartlink/analytics?id=clp123abc456def" \
  -H "Authorization: Bearer rlk_your_api_key_here"

Response:


{
  "success": true,
  "message": "Analytics retrieved successfully",
  "data": {
    "smartlinkId": "clp123abc456def",
    "smartlinkName": "My First App",
    "totalClicks": 1520,
    "totalQrCodeScans": 45,
    "totalFallBack": 12,
    "analyticsData": [
      {
        "date": "2024-01-15",
        "clicks": 150,
        "qrScans": 5,
        "countries": {"US": 100, "UK": 30, "CA": 20},
        "devices": {"mobile": 120, "desktop": 30}
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

JavaScript Example


// Initialize API client
const RELINK_API_KEY = 'rlk_your_api_key_here';
const BASE_URL = 'https://relink.is/api/v1';
 
const headers = {
  'Authorization': `Bearer ${RELINK_API_KEY}`,
  'Content-Type': 'application/json'
};
 
// Create a smartlink
async function createSmartlink() {
  const response = await fetch(`${BASE_URL}/smartlink`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      configuration: {
        smartlinkName: "My JS App",
        smartlinkType: "App",
        appStoreLink: "https://apps.apple.com/app/myapp",
        fallBackLink: "https://myapp.com"
      },
      openGraph: {
        title: "Download My App",
        description: "Built with JavaScript"
      }
    })
  });
  
  const result = await response.json();
  
  if (result.success) {
    console.log('Smartlink created:', result.data.relink);
    return result.data;
  } else {
    console.error('Error:', result.error.message);
    throw new Error(result.error.message);
  }
}
 
// Update a smartlink
async function updateSmartlink(smartlinkId, updates) {
  const response = await fetch(`${BASE_URL}/smartlink`, {
    method: 'PATCH',
    headers,
    body: JSON.stringify({
      id: smartlinkId,
      ...updates
    })
  });
  
  const result = await response.json();
  
  if (result.success) {
    console.log('Smartlink updated successfully');
    return result.data;
  } else {
    console.error('Update failed:', result.error.message);
    throw new Error(result.error.message);
  }
}
 
// Get analytics
async function getAnalytics(smartlinkId) {
  const response = await fetch(`${BASE_URL}/smartlink/analytics?id=${smartlinkId}`, {
    headers
  });
  
  const result = await response.json();
  
  if (result.success) {
    console.log('Total clicks:', result.data.totalClicks);
    return result.data;
  } else {
    console.error('Analytics fetch failed:', result.error.message);
    throw new Error(result.error.message);
  }
}
 
// Usage
createSmartlink()
  .then(smartlink => {
    console.log('Created smartlink:', smartlink.id);
    
    // Update it
    return updateSmartlink(smartlink.id, {
      openGraph: {
        title: "Updated Title"
      }
    });
  })
  .then(() => {
    console.log('Update successful');
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Python Example


import requests
import json
 
# Configuration
API_KEY = "rlk_your_api_key_here"
BASE_URL = "https://relink.is/api/v1"
 
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}
 
def create_smartlink():
    """Create a new smartlink"""
    data = {
        "configuration": {
            "smartlinkName": "My Python App",
            "smartlinkType": "App",
            "appStoreLink": "https://apps.apple.com/app/myapp",
            "fallBackLink": "https://myapp.com"
        },
        "openGraph": {
            "title": "Download My App",
            "description": "Built with Python"
        }
    }
    
    response = requests.post(f"{BASE_URL}/smartlink", headers=headers, json=data)
    result = response.json()
    
    if result["success"]:
        print(f"Smartlink created: {result['data']['relink']}")
        return result["data"]
    else:
        print(f"Error: {result['error']['message']}")
        raise Exception(result["error"]["message"])
 
def update_smartlink(smartlink_id, updates):
    """Update a smartlink with partial data"""
    data = {"id": smartlink_id, **updates}
    
    response = requests.patch(f"{BASE_URL}/smartlink", headers=headers, json=data)
    result = response.json()
    
    if result["success"]:
        print("Smartlink updated successfully")
        return result["data"]
    else:
        print(f"Update failed: {result['error']['message']}")
        raise Exception(result["error"]["message"])
 
def get_analytics(smartlink_id):
    """Get analytics for a smartlink"""
    response = requests.get(f"{BASE_URL}/smartlink/analytics", 
                          headers=headers, 
                          params={"id": smartlink_id})
    result = response.json()
    
    if result["success"]:
        print(f"Total clicks: {result['data']['totalClicks']}")
        return result["data"]
    else:
        print(f"Analytics fetch failed: {result['error']['message']}")
        raise Exception(result["error"]["message"])
 
# Usage
try:
    # Create smartlink
    smartlink = create_smartlink()
    print(f"Created smartlink: {smartlink['id']}")
    
    # Update it
    update_smartlink(smartlink["id"], {
        "openGraph": {
            "title": "Updated Python Title"
        }
    })
    
    # Get analytics
    analytics = get_analytics(smartlink["id"])
    print(f"Analytics: {analytics}")
    
except Exception as e:
    print(f"Error: {e}")

Error Handling

The API returns standardized error responses:


{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": [
      {
        "path": "configuration.smartlinkUrl",
        "message": "Smartlink URL can only contain latin characters and numbers"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Always check the success field and handle errors appropriately:


const result = await response.json();
 
if (!result.success) {
  console.error('API Error:', result.error.message);
  
  // Handle validation errors
  if (result.error.details) {
    result.error.details.forEach(detail => {
      console.error(`${detail.path}: ${detail.message}`);
    });
  }
  
  throw new Error(result.error.message);
}

Next Steps

🚀 Explore More

API Endpoints - Complete endpoint reference
Types & Schemas - Detailed schemas for all smartlink types
Examples - More code examples and use cases
Analytics - Comprehensive analytics documentation

🛠 Development Tools

Postman Collection - Ready-to-use API collection
Error Handling - Comprehensive error reference
Validation Rules - Field validation details

📚 Best Practices

Best Practices - Optimization and security tips
Rate Limiting - Usage limits and guidelines
Troubleshooting - Common issues and solutions

Support

Need help? Check out:

Troubleshooting Guide - Common issues and solutions
API Documentation - Complete API reference
Support Portal - Contact our team

🎉 You’re ready to build amazing things with the Relink API!