API Reference

FluxLink provides a RESTful API that allows you to integrate with the service directly if you prefer not to use one of our SDKs.

Authentication

All API requests must be authenticated using an API key. Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

Base URL

https://your-fluxlink-api.com/api

Replace your-fluxlink-api.com with your actual FluxLink API domain.

Endpoints

Authentication

Register a new user

POST /auth/register

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "securepassword"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "user123",
      "name": "John Doe",
      "email": "john@example.com"
    },
    "token": "jwt-token-here"
  }
}

Login

POST /auth/login

Request Body:

{
  "email": "john@example.com",
  "password": "securepassword"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "user123",
      "name": "John Doe",
      "email": "john@example.com"
    },
    "token": "jwt-token-here"
  }
}

Get current user

GET /auth/me

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "user123",
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

Generate API key

POST /auth/api-keys

Request Body:

{
  "name": "My App API Key"
}

Response:

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "key123",
      "name": "My App API Key",
      "key": "flx_1234567890abcdef",
      "createdAt": "2023-01-01T00:00:00.000Z"
    }
  }
}

Delete API key

DELETE /auth/api-keys/:id

Response:

{
  "success": true,
  "data": null
}

Links

Create a new link

POST /links

Request Body:

{
  "title": "Product Link",
  "defaultUrl": "https://example.com/fallback",
  "androidLink": {
    "url": "myapp://product/123",
    "appPackageName": "com.example.myapp",
    "minimumVersion": "1.0.0"
  },
  "iosLink": {
    "url": "myapp://product/123",
    "bundleId": "com.example.myapp",
    "minimumVersion": "1.0.0"
  },
  "desktopUrl": "https://example.com/desktop",
  "customParameters": {
    "campaign": "summer_promo",
    "medium": "email"
  }
}

Response:

{
  "success": true,
  "data": {
    "link": {
      "id": "link123",
      "url": "https://flxlnk.com/abc123",
      "title": "Product Link",
      "defaultUrl": "https://example.com/fallback",
      "androidLink": {
        "url": "myapp://product/123",
        "appPackageName": "com.example.myapp",
        "minimumVersion": "1.0.0"
      },
      "iosLink": {
        "url": "myapp://product/123",
        "bundleId": "com.example.myapp",
        "minimumVersion": "1.0.0"
      },
      "desktopUrl": "https://example.com/desktop",
      "customParameters": {
        "campaign": "summer_promo",
        "medium": "email"
      },
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z"
    }
  }
}

Get all links

GET /links

Query Parameters:

page (optional): Page number for pagination (default: 1)
limit (optional): Number of items per page (default: 10)
sortBy (optional): Field to sort by (default: createdAt)
sortDirection (optional): Sort direction, 'asc' or 'desc' (default: desc)

Response:

{
  "success": true,
  "data": {
    "links": [
      {
        "id": "link123",
        "url": "https://flxlnk.com/abc123",
        "title": "Product Link",
        "defaultUrl": "https://example.com/fallback",
        "createdAt": "2023-01-01T00:00:00.000Z",
        "updatedAt": "2023-01-01T00:00:00.000Z"
      }
      // More links...
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "limit": 10,
      "pages": 5
    }
  }
}

Get a specific link

GET /links/:id

Response:

{
  "success": true,
  "data": {
    "link": {
      "id": "link123",
      "url": "https://flxlnk.com/abc123",
      "title": "Product Link",
      "defaultUrl": "https://example.com/fallback",
      "androidLink": {
        "url": "myapp://product/123",
        "appPackageName": "com.example.myapp",
        "minimumVersion": "1.0.0"
      },
      "iosLink": {
        "url": "myapp://product/123",
        "bundleId": "com.example.myapp",
        "minimumVersion": "1.0.0"
      },
      "desktopUrl": "https://example.com/desktop",
      "customParameters": {
        "campaign": "summer_promo",
        "medium": "email"
      },
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z"
    }
  }
}

Update a link

PUT /links/:id

Request Body:

{
  "title": "Updated Product Link",
  "defaultUrl": "https://example.com/new-fallback",
  "androidLink": {
    "minimumVersion": "2.0.0"
  }
}

Response:

{
  "success": true,
  "data": {
    "link": {
      "id": "link123",
      "url": "https://flxlnk.com/abc123",
      "title": "Updated Product Link",
      "defaultUrl": "https://example.com/new-fallback",
      "androidLink": {
        "url": "myapp://product/123",
        "appPackageName": "com.example.myapp",
        "minimumVersion": "2.0.0"
      },
      "iosLink": {
        "url": "myapp://product/123",
        "bundleId": "com.example.myapp",
        "minimumVersion": "1.0.0"
      },
      "desktopUrl": "https://example.com/desktop",
      "customParameters": {
        "campaign": "summer_promo",
        "medium": "email"
      },
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-02T00:00:00.000Z"
    }
  }
}

Delete a link

DELETE /links/:id

Response:

{
  "success": true,
  "data": null
}

Analytics

Get link analytics

GET /analytics/links/:id

Query Parameters:

startDate (optional): Start date for analytics (ISO format)
endDate (optional): End date for analytics (ISO format)
timeBucket (optional): Time bucket for time series data ('hour', 'day', 'week', 'month')

Response:

{
  "success": true,
  "data": {
    "analytics": {
      "totalClicks": 1250,
      "uniqueClicks": 870,
      "platforms": {
        "android": 450,
        "ios": 380,
        "desktop": 420
      },
      "countries": {
        "US": 520,
        "UK": 180,
        "CA": 150,
        "Other": 400
      },
      "browsers": {
        "Chrome": 480,
        "Safari": 390,
        "Firefox": 210,
        "Other": 170
      },
      "devices": {
        "Mobile": 830,
        "Desktop": 420
      },
      "timeSeries": [
        {
          "date": "2023-01-01T00:00:00.000Z",
          "clicks": 45
        }
        // More time periods...
      ]
    }
  }
}

Get summary analytics

GET /analytics/summary

Response:

{
  "success": true,
  "data": {
    "summary": {
      "totalLinks": 156,
      "totalClicks": 25680,
      "activeLinks": 142,
      "topLinks": [
        {
          "id": "link123",
          "title": "Product Link",
          "clicks": 1250
        }
        // More links...
      ]
    }
  }
}

Error Handling

The API returns standard HTTP status codes along with a JSON response body:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request was invalid",
    "details": [
      {
        "field": "title",
        "message": "Title is required"
      }
    ]
  }
}

Common error codes:

UNAUTHORIZED: Authentication failed
FORBIDDEN: Permission denied
NOT_FOUND: Resource not found
INVALID_REQUEST: Invalid request parameters
INTERNAL_ERROR: Server error

Rate Limiting

The API implements rate limiting to prevent abuse. Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

SDK Reference