Skip to Content
DocumentationAPI Endpoints

API Endpoints

Base URL

All API requests should be made to: https://relink.is/api/v1/

Authentication

Validate API Key

Endpoint: GET /api/v1/validate

Description: Test if your API key is valid and working properly.

Headers:

Authorization: Bearer rlk_your_api_key_here

Success Response:

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

Error Response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key format"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Endpoint: GET /api/v1/smartlink

Description: Retrieve all active smartlinks for the authenticated user.

Headers:

Authorization: Bearer rlk_your_api_key_here

Success Response:

{
  "success": true,
  "message": "Smartlinks retrieved successfully",
  "data": [
    {
      "id": "clp123abc456def",
      "status": "Active",
      "type": "App",
      "userId": "clp789user123",
      "relink": "https://relink.is/myapp",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T14:45:00.000Z",
      "configuration": {
        "smartlinkName": "My App",
        "smartlinkUrl": "myapp",
        "smartlinkType": "App",
        "appStoreLink": "https://apps.apple.com/app/myapp",
        "googlePlayLink": "https://play.google.com/store/apps/details?id=myapp"
      },
      "analytics": {
        "totalClicks": 1520,
        "totalQrCodeScans": 45,
        "totalFallBack": 12
      }
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Endpoint: GET /api/v1/smartlink?id={smartlink_id}

Description: Retrieve a specific smartlink by ID.

Parameters:

  • id (query): The smartlink ID

Success Response: Single smartlink object with complete configuration and related data.

Endpoint: POST /api/v1/smartlink

Description: Create a new smartlink using the GraphQL-like reactive body approach. The request body automatically adapts based on the smartlink type specified.

Headers:

Content-Type: application/json
Authorization: Bearer rlk_your_api_key_here
{
  "configuration": {
    "smartlinkName": "Test App",
    "smartlinkType": "App"
  }
}
{
  "configuration": {
    "smartlinkName": "Full App",
    "smartlinkUrl": "fullapp",
    "smartlinkType": "App",
    "appStoreLink": "https://apps.apple.com/app/fullapp",
    "googlePlayLink": "https://play.google.com/store/apps/details?id=fullapp",
    "fallBackLink": "https://fullapp.com"
  },
  "openGraph": {
    "title": "Full App",
    "description": "A comprehensive test app",
    "imageUrl": "https://fullapp.com/og.jpg"
  }
}

Create URL Shortener

{
  "configuration": {
    "smartlinkName": "Test URL",
    "smartlinkUrl": "testurl",
    "smartlinkType": "Url"
  },
  "shortener": {
    "url": "https://google.com"
  }
}

Create Landing Page

{
  "configuration": {
    "smartlinkName": "Test Landing",
    "smartlinkUrl": "testlanding",
    "smartlinkType": "Landing"
  },
  "landing": {
    "title": "My Landing Page",
    "description": "Test landing page",
    "themeColor": "#007bff"
  },
  "landingButtons": [
    {
      "title": "Button 1",
      "link": "https://example.com"
    }
  ]
}

Create QR Tag

{
  "configuration": {
    "smartlinkName": "Test QR",
    "smartlinkUrl": "testqr",
    "smartlinkType": "QRTag"
  },
  "qrTag": {
    "title": "Test QR Tag",
    "description": "Test QR description"
  },
  "qrTagButtons": [
    {
      "title": "QR Button",
      "link": "https://example.com",
      "preset": "link"
    }
  ]
}

Create Digital Card

{
  "configuration": {
    "smartlinkName": "Test DigiCard",
    "smartlinkUrl": "testcard",
    "smartlinkType": "DigiCard"
  },
  "digiCard": {
    "title": "John Doe",
    "jobTitle": "Developer",
    "company": "Test Company"
  },
  "digiCardButtons": [
    {
      "title": "Contact",
      "link": "mailto:[email protected]",
      "preset": "email"
    }
  ]
}

Create Text Bin

{
  "configuration": {
    "smartlinkName": "Test TxtBin",
    "smartlinkUrl": "testtxt",
    "smartlinkType": "TxtBin"
  },
  "txtBin": {
    "title": "Test Text",
    "description": "Test text description",
    "text": "This is a test text content"
  }
}

Success Response:

{
  "success": true,
  "message": "Smartlink created successfully",
  "data": {
    "id": "clp123abc456def",
    "status": "Active",
    "type": "App",
    "relink": "https://relink.is/testapp",
    "configuration": { /* complete configuration */ },
    "analytics": { /* analytics data */ }
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Endpoint: PATCH /api/v1/smartlink

Description: Perform partial updates on existing smartlinks. Only the fields you specify will be updated, similar to GraphQL mutations. Zod validates and ignores extra fields.

Headers:

Content-Type: application/json
Authorization: Bearer rlk_your_api_key_here
{
  "id": "clp123abc456def",
  "configuration": {
    "appStoreLink": "https://apps.apple.com/app/myapp"
  }
}

Update Only Open Graph Data

{
  "id": "clp123abc456def",
  "openGraph": {
    "title": "Updated App Title",
    "description": "Updated app description"
  }
}

Update Landing Buttons

{
  "id": "clp123abc456def",
  "landingButtons": [
    {
      "title": "New Button",
      "link": "https://example.com/new",
      "iconUrl": "https://example.com/icon.png"
    }
  ]
}

Update Digital Card Contact Info

{
  "id": "clp123abc456def",
  "digiCard": {
    "jobTitle": "Lead Software Engineer",
    "company": "New Tech Company Ltd.",
    "ctaText": "Let's Build Something Amazing!"
  }
}

Update Text Bin Content

{
  "id": "clp123abc456def",
  "txtBin": {
    "title": "Updated React Component",
    "description": "Enhanced React component with TypeScript",
    "text": "import React, { useState } from 'react';\n\nfunction Counter() {\n  const [count, setCount] = useState(0);\n  return <button onClick={() => setCount(count + 1)}>{count}</button>;\n}"
  }
}

Endpoint: DELETE /api/v1/smartlink

Description: Soft delete a smartlink (sets status to ‘Deleted’).

Headers:

Content-Type: application/json
Authorization: Bearer rlk_your_api_key_here

Request Body:

{
  "smartlinkId": "clp123abc456def"
}

Success Response:

{
  "success": true,
  "message": "Smartlink deleted successfully",
  "data": null,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Analytics

Endpoint: GET /api/v1/smartlink/analytics?id={smartlink_id}

Description: Retrieve detailed analytics for a specific smartlink.

Success Response:

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

Get Analytics Summary

Endpoint: GET /api/v1/analytics/summary

Description: Retrieve comprehensive analytics summary for all user smartlinks.

Success Response:

{
  "success": true,
  "message": "Analytics summary retrieved successfully",
  "data": {
    "user": {
      "id": "clp789user123",
      "email": "[email protected]",
      "subscription": "Professional"
    },
    "summary": {
      "totalSmartlinks": 25,
      "totalClicks": 15240,
      "totalQrCodeScans": 450,
      "totalFallbacks": 120
    },
    "smartlinks": [
      {
        "id": "clp123abc456def",
        "name": "My App",
        "type": "App",
        "clicks": 1520,
        "qrScans": 45
      }
    ],
    "recentActivity": [
      {
        "smartlinkId": "clp123abc456def",
        "action": "click",
        "timestamp": "2024-01-15T14:30:00.000Z",
        "country": "US",
        "device": "mobile"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Error Responses

All endpoints return standardized error responses:

Validation Error

{
  "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"
}

Not Found Error

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Smartlink not found"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Subscription Limit Error

{
  "success": false,
  "error": {
    "code": "SUBSCRIPTION_LIMIT_REACHED",
    "message": "Subscription limit reached"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
Getting API KeysTypes & Schemas