{ "openapi": "3.1.0", "info": { "title": "TrimLynk REST API v1", "version": "1.2.0", "description": "TrimLynk is a modern, privacy-first URL shortening and link intelligence platform. This API provides programmatic access to link shortening, custom QR code generation, click analytics, geo-targeting, and Link-in-Bio management.\n\n### API Versioning Policy\nTrimLynk adopts URL path versioning (`/v1/...`). Clients are encouraged to target versioned endpoints (`https://api.trimlynk.com/v1` or `https://trimlynk.com/api/v1`). Unversioned paths (`/api/...`) operate as aliases to `/v1/...` for 100% backward compatibility.\n\n### Deprecation & Sunset Policy\nWhen an endpoint or API version is scheduled for deprecation, TrimLynk signals this via standard RFC 8594 / RFC 9285 response headers:\n- `Deprecation: @` (or `true`) indicating the deprecation date.\n- `Sunset: ` indicating the date after which the endpoint will be turned down.\n- `Link: ; rel=\"deprecation\"` linking to migration documentation.\n\n### Rate Limiting & Response Headers\nAll API endpoints return standard IETF RateLimit headers:\n- `RateLimit-Limit`: Request limit quota per window (default: 1000 requests/hour)\n- `RateLimit-Remaining`: Remaining request allowance\n- `RateLimit-Reset`: Seconds until quota reset\n- `Retry-After`: Number of seconds to wait before retrying (returned on HTTP 429 status)", "contact": { "name": "TrimLynk Support", "email": "ankygaur9972@gmail.com", "url": "https://trimlynk.com/contact" }, "license": { "name": "TrimLynk Terms of Service", "url": "https://trimlynk.com/terms" } }, "servers": [ { "url": "https://api.trimlynk.com/v1", "description": "Primary Production API Subdomain (v1)" }, { "url": "https://trimlynk.com/api/v1", "description": "Root Production API Server (v1)" }, { "url": "https://api.trimlynk.com", "description": "Primary Production API Subdomain (Unversioned Alias)" }, { "url": "https://trimlynk.com/api", "description": "Root Production Server (Unversioned Alias)" }, { "url": "http://localhost:3001/v1", "description": "Local Development Server (v1)" }, { "url": "http://localhost:3001", "description": "Local Development Server (Root)" } ], "paths": { "/api/free-urls/shorten": { "post": { "operationId": "shortenFreeUrl", "summary": "Create an instant anonymous short URL", "description": "Shortens a URL without requiring authentication. Free links expire after 7 days.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "longUrl" ], "properties": { "longUrl": { "type": "string", "format": "uri", "description": "The destination URL to shorten", "example": "https://example.com/very/long/url/path" }, "customCode": { "type": "string", "description": "Optional custom alias slug (alphanumeric and dashes)", "example": "my-promo" } } } } } }, "responses": { "201": { "description": "Short URL created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortUrlResponse" } } } }, "400": { "description": "Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/urls": { "post": { "operationId": "createUrl", "summary": "Create a new shortened URL with advanced options", "description": "Creates a shortened URL with support for custom slugs, password protection, expiration dates, UTM parameters, and device/geo-targeting.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "OAuth2": [ "write:links" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "longUrl" ], "properties": { "title": { "type": "string", "example": "My Campaign Link" }, "longUrl": { "type": "string", "format": "uri", "example": "https://example.com/product" }, "customUrl": { "type": "string", "example": "spring-sale" }, "password": { "type": "string", "description": "Optional password to protect the link" }, "expiresAt": { "type": "string", "format": "date-time" }, "clickLimit": { "type": "integer", "minimum": 1 }, "utmSource": { "type": "string", "example": "newsletter" }, "utmMedium": { "type": "string", "example": "email" }, "utmCampaign": { "type": "string", "example": "spring2026" }, "isCloaked": { "type": "boolean", "default": false }, "privacyMode": { "type": "boolean", "default": false } } } } } }, "responses": { "201": { "description": "URL created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlItem" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "get": { "operationId": "listUrls", "summary": "List shortened URLs for the authenticated user", "description": "Returns a paginated list of all URLs created by the authenticated user.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "OAuth2": [ "read:links" ] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Page number for pagination" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Number of items per page" } ], "responses": { "200": { "description": "List of user URLs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UrlItem" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/urls/{id}": { "get": { "operationId": "getUrlById", "summary": "Get details of a shortened URL", "description": "Retrieves comprehensive metadata and settings for a specific URL ID.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "OAuth2": [ "read:links" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique URL identifier" } ], "responses": { "200": { "description": "URL details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "operationId": "updateUrlById", "summary": "Update a shortened URL", "description": "Updates destination, title, custom slug, password, click limits, or active status.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "OAuth2": [ "write:links" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "originalUrl": { "type": "string", "format": "uri" }, "customUrl": { "type": "string" }, "password": { "type": "string" }, "isActive": { "type": "boolean" }, "clickLimit": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Updated URL item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "operationId": "deleteUrlById", "summary": "Delete a shortened URL", "description": "Permanently deletes a shortened URL and its associated analytics history.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "OAuth2": [ "write:links" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/api/urls/redirect/{shortUrl}": { "get": { "operationId": "resolveShortUrl", "summary": "Resolve destination URL and metadata for a short link", "description": "Lookup short code or custom alias to determine destination URL, password protection status, and routing rules.", "parameters": [ { "name": "shortUrl", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Short code or custom alias" } ], "responses": { "200": { "description": "Resolved URL metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectResponse" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/api/urls/redirect/{shortUrl}/verify-password": { "post": { "operationId": "verifyUrlPassword", "summary": "Verify password for a protected link", "description": "Validates the bcrypt password hash for a password-protected short link to unlock the destination URL.", "parameters": [ { "name": "shortUrl", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string", "example": "mypassword" } } } } } }, "responses": { "200": { "description": "Password verified, returns destination metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/clicks/analytics/{urlId}": { "get": { "operationId": "getUrlAnalytics", "summary": "Get comprehensive click analytics for a URL", "description": "Retrieves aggregated click counts, country breakdown, device breakdown, browser stats, and referrer telemetry.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "OAuth2": [ "read:analytics" ] } ], "parameters": [ { "name": "urlId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Aggregated analytics metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsSummary" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/api/clicks": { "get": { "operationId": "listClicks", "summary": "List all click events across all user links", "description": "Fetches raw telemetry click stream for the authenticated account.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "OAuth2": [ "read:analytics" ] } ], "responses": { "200": { "description": "Array of click records", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClickItem" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/analytics-ai/query": { "post": { "operationId": "queryAnalyticsWithAi", "summary": "Ask natural language questions about click metrics", "description": "Uses LLM reasoning against the user's aggregated link performance data to answer analytical queries.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "OAuth2": [ "read:analytics" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "example": "Which countries generated the most clicks this week?" } } } } } }, "responses": { "200": { "description": "AI analysis and supporting data", "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string" }, "data": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys for the authenticated user", "description": "Returns all active and revoked API keys associated with the account.", "security": [ { "BearerAuth": [] }, { "OAuth2": [ "read:profile" ] } ], "responses": { "200": { "description": "Array of API keys", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyItem" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "operationId": "createApiKey", "summary": "Generate a new developer API key", "description": "Generates a SHA-256 hashed API key with prefix 'tk_' for programmatic integration.", "security": [ { "BearerAuth": [] }, { "OAuth2": [ "write:profile" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Production CLI Service" }, "expiresInDays": { "type": "integer", "default": 90 } } } } } }, "responses": { "201": { "description": "API Key created (shown once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/keys/{id}": { "delete": { "operationId": "deleteApiKey", "summary": "Revoke an API key", "description": "Revokes an API key permanently so it can no longer be used for authentication.", "security": [ { "BearerAuth": [] }, { "OAuth2": [ "write:profile" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Key revoked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/dynamic-qr": { "post": { "operationId": "createDynamicQr", "summary": "Create a Dynamic QR Code", "description": "Creates a redirectable Dynamic QR code whose target URL can be updated at any time without reprinting.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "OAuth2": [ "write:qr" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "targetUrl" ], "properties": { "title": { "type": "string", "example": "Product Packaging QR" }, "targetUrl": { "type": "string", "format": "uri", "example": "https://example.com/promo" } } } } } }, "responses": { "201": { "description": "Dynamic QR Code created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicQrItem" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "get": { "operationId": "listDynamicQrs", "summary": "List Dynamic QR Codes", "description": "Returns all Dynamic QR codes created by the user.", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] }, { "OAuth2": [ "read:links" ] } ], "responses": { "200": { "description": "Array of Dynamic QR codes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DynamicQrItem" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/public-stats": { "get": { "operationId": "getPublicStats", "summary": "Get aggregate platform statistics", "description": "Returns platform-wide metrics including total links shortened, total clicks redirected, and active workspaces (cached 5 minutes).", "responses": { "200": { "description": "Public platform metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalLinks": { "type": "integer", "example": 125000 }, "totalClicks": { "type": "integer", "example": 4500000 }, "totalUsers": { "type": "integer", "example": 8900 } } } } } } } } }, "/api/auth/register": { "post": { "operationId": "registerUser", "summary": "Register a new user account", "description": "Creates a new user account with email and password, returning a JWT token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email", "password" ], "properties": { "name": { "type": "string", "example": "Alex Rivera" }, "email": { "type": "string", "format": "email", "example": "alex@example.com" }, "password": { "type": "string", "format": "password", "example": "SecureP@ss123" } } } } } }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/api/auth/login": { "post": { "operationId": "loginUser", "summary": "Authenticate with email and password", "description": "Validates user credentials and returns a JWT authentication session token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "alex@example.com" }, "password": { "type": "string", "format": "password", "example": "SecureP@ss123" } } } } } }, "responses": { "200": { "description": "Authenticated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/auth/me": { "get": { "operationId": "getCurrentUser", "summary": "Get profile of current authenticated user", "description": "Returns current user account details, role, and workspace memberships.", "security": [ { "BearerAuth": [] }, { "OAuth2": [ "read:profile" ] } ], "responses": { "200": { "description": "User profile data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfile" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API Key prefixed with 'tk_'" }, "OAuth2": { "type": "oauth2", "description": "TrimLynk OAuth 2.0 authentication with scoped permissions.", "flows": { "authorizationCode": { "authorizationUrl": "https://trimlynk.com/api/v1/oauth/google", "tokenUrl": "https://trimlynk.com/api/v1/oauth/token", "scopes": { "read:links": "Read user shortened links and metadata", "write:links": "Create, modify, and delete shortened links", "read:analytics": "Access click telemetry and visitor metrics", "write:qr": "Create and manage dynamic QR codes", "read:profile": "Access user profile and account details", "write:profile": "Update user profile and credentials" } } } } }, "schemas": { "ShortUrlResponse": { "type": "object", "properties": { "shortCode": { "type": "string", "example": "x8K2mQ" }, "shortUrl": { "type": "string", "example": "https://trimlynk.com/x8K2mQ" }, "longUrl": { "type": "string", "example": "https://example.com" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "UrlItem": { "type": "object", "properties": { "id": { "type": "string", "example": "cuid12345" }, "title": { "type": "string", "example": "Landing Page" }, "originalUrl": { "type": "string", "example": "https://example.com" }, "shortUrl": { "type": "string", "example": "x8K2mQ" }, "customUrl": { "type": "string", "nullable": true, "example": "promo" }, "currentClicks": { "type": "integer", "example": 42 }, "isActive": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "RedirectResponse": { "type": "object", "properties": { "id": { "type": "string" }, "originalUrl": { "type": "string", "nullable": true }, "shortUrl": { "type": "string" }, "hasPassword": { "type": "boolean" }, "isExpired": { "type": "boolean" }, "isActive": { "type": "boolean" } } }, "ClickItem": { "type": "object", "properties": { "id": { "type": "string" }, "urlId": { "type": "string" }, "country": { "type": "string", "example": "US" }, "device": { "type": "string", "example": "desktop" }, "browser": { "type": "string", "example": "Chrome" }, "createdAt": { "type": "string", "format": "date-time" } } }, "ApiKeyItem": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "example": "Production CLI Service" }, "keyPreview": { "type": "string", "example": "tk_live_...9f81" }, "isActive": { "type": "boolean", "example": true }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "ApiKeyCreatedResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key": { "type": "string", "example": "tk_live_a1b2c3d4e5f6g7h8i9j0" }, "message": { "type": "string", "example": "Copy this key now. It will not be shown again." } } }, "DynamicQrItem": { "type": "object", "properties": { "id": { "type": "string" }, "shortCode": { "type": "string", "example": "qr_8K2m" }, "targetUrl": { "type": "string", "example": "https://example.com/promo" }, "scans": { "type": "integer", "example": 18 }, "createdAt": { "type": "string", "format": "date-time" } } }, "AuthResponse": { "type": "object", "properties": { "token": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "user": { "$ref": "#/components/schemas/UserProfile" } } }, "UserProfile": { "type": "object", "properties": { "id": { "type": "string", "example": "usr_123" }, "name": { "type": "string", "example": "Alex Rivera" }, "email": { "type": "string", "example": "alex@example.com" }, "role": { "type": "string", "example": "USER" } } }, "AnalyticsSummary": { "type": "object", "properties": { "totalClicks": { "type": "integer", "example": 150 }, "uniqueVisitors": { "type": "integer", "example": 110 }, "countryStats": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "example": "United States" }, "count": { "type": "integer", "example": 60 } } } }, "deviceStats": { "type": "array", "items": { "type": "object", "properties": { "device": { "type": "string", "example": "mobile" }, "count": { "type": "integer", "example": 85 } } } } } }, "ErrorDetails": { "type": "object", "properties": { "code": { "type": "string", "example": "INVALID_PARAMS" }, "message": { "type": "string", "example": "The provided parameters are invalid." }, "resolution": { "type": "string", "example": "Ensure longUrl is a valid HTTP or HTTPS URL." } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetails" }, "message": { "type": "string", "example": "The provided parameters are invalid." }, "timestamp": { "type": "string", "format": "date-time" } } } }, "responses": { "BadRequestError": { "description": "Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnauthorizedError": { "description": "Authentication required or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFoundError": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }