{ "openapi": "3.0.0", "info": { "title": "URLHive API Documentation", "description": "API documentation for URLHive Application.", "contact": { "email": "support@urlhive.net" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.urlhive.net", "description": "URLHive API v1 Server" } ], "paths": { "/v1/bio-links": { "post": { "tags": [ "Bio Links" ], "summary": "Add Bio Link", "description": "Add a new link to bio page.", "operationId": "storeBioLink", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "url" ], "properties": { "title": { "type": "string", "example": "My Website", "maxLength": 100 }, "url": { "type": "string", "format": "url", "example": "https://example.com", "maxLength": 500 }, "icon": { "type": "string", "example": "fa-globe", "maxLength": 50 } }, "type": "object" } } } }, "responses": { "201": { "description": "Link added successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "My Website" }, "url": { "type": "string", "example": "https://example.com" }, "order": { "type": "integer", "example": 1 } }, "type": "object" }, "message": { "type": "string", "example": "Link added successfully." } }, "type": "object" } } } }, "400": { "description": "Bio Page Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/bio-links/{id}": { "put": { "tags": [ "Bio Links" ], "summary": "Update Bio Link", "description": "Update an existing link.", "operationId": "updateBioLink", "parameters": [ { "name": "id", "in": "path", "description": "ID of the link", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "maxLength": 100 }, "url": { "type": "string", "format": "url", "maxLength": 500 }, "icon": { "type": "string", "maxLength": 50 }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Link updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" }, "message": { "type": "string", "example": "Link updated successfully." } }, "type": "object" } } } }, "404": { "description": "Link Not Found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Bio Links" ], "summary": "Delete Bio Link", "description": "Delete a link.", "operationId": "deleteBioLink", "parameters": [ { "name": "id", "in": "path", "description": "ID of the link", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Link deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Link deleted successfully." } }, "type": "object" } } } }, "404": { "description": "Link Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/bio-links/reorder": { "post": { "tags": [ "Bio Links" ], "summary": "Reorder Bio Links", "description": "Reorder links.", "operationId": "reorderBioLinks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "order": { "type": "integer", "example": 2 } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Links reordered successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Links reordered successfully." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/v1/bio-links/{id}/click": { "post": { "tags": [ "Bio Links" ], "summary": "Track Click", "description": "Track link click (public).", "operationId": "trackBioLinkClick", "parameters": [ { "name": "id", "in": "path", "description": "ID of the link", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Click tracked", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "url": { "type": "string", "example": "https://example.com" } }, "type": "object" } } } }, "404": { "description": "Link Not Found" } } } }, "/v1/bio/links/{id}/stats": { "get": { "tags": [ "Bio Links" ], "summary": "Get Bio Link Stats", "description": "Get analytics stats for a specific bio link.", "operationId": "getBioLinkStats", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Link Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/bio-page": { "get": { "tags": [ "Bio Pages" ], "summary": "Get Bio Page", "description": "Get the current user's bio page.", "operationId": "getBioPage", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "username": { "type": "string", "example": "johndoe" }, "title": { "type": "string", "example": "John's Links" }, "bio": { "type": "string", "example": "Welcome to my page" }, "theme": { "type": "string", "example": "dark" }, "avatar_url": { "type": "string", "example": "https://example.com/avatar.jpg" }, "links": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Bio Page Not Found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Bio page not found." }, "data": { "type": "null" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Bio Pages" ], "summary": "Save Bio Page", "description": "Create or update bio page.", "operationId": "storeBioPage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "username" ], "properties": { "username": { "type": "string", "example": "johndoe", "maxLength": 30, "minLength": 3 }, "title": { "type": "string", "example": "John's Bio", "maxLength": 100 }, "bio": { "type": "string", "example": "My personal links", "maxLength": 500 }, "theme": { "type": "string", "example": "dark", "enum": [ "minimal", "dark", "colorful" ] }, "avatar_url": { "type": "string", "format": "url", "maxLength": 500 }, "pixels": { "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Bio page saved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" }, "message": { "type": "string", "example": "Bio page saved successfully." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/v1/bio/{username}": { "get": { "tags": [ "Bio Pages" ], "summary": "Get Public Bio Page", "description": "Get public bio page by username.", "operationId": "getPublicBioPage", "parameters": [ { "name": "username", "in": "path", "description": "Username of the bio page", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "username": { "type": "string" }, "title": { "type": "string" }, "bio": { "type": "string" }, "theme": { "type": "string" }, "avatar_url": { "type": "string" }, "links": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string", "format": "url" }, "icon": { "type": "string" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Bio Page Not Found" } } } }, "/v1/bio/stats": { "get": { "tags": [ "Bio Pages" ], "summary": "Get Bio Page Stats", "description": "Get analytics statistics for the current user's bio page.", "operationId": "getBioPageStats", "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Bio Page Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/bio/export": { "get": { "tags": [ "Bio Pages" ], "summary": "Export Bio Page Stats", "description": "Export analytics data for the current user's bio page as CSV.", "operationId": "exportBioPageStats", "responses": { "200": { "description": "CSV file download" }, "404": { "description": "Bio Page Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/track/conversion": { "post": { "tags": [ "Conversions" ], "summary": "Track Conversion (S2S)", "description": "Track a conversion event.", "operationId": "a306bfcc8ee9d0a0478fc67ee7815a63", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "hive_id": { "description": "The Click ID captured from the ?hive_id= URL parameter", "type": "string", "example": "abc123" }, "event_name": { "description": "Name of the action (e.g., purchase, signup)", "type": "string", "example": "purchase" }, "value": { "description": "Monetary or numerical value of the conversion", "type": "number", "format": "float", "example": 49.99, "nullable": true }, "metadata": { "description": "Additional context (e.g., order_id, items_count)", "type": "object", "nullable": true, "additionalProperties": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Conversion tracked successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Conversion tracked successfully" } }, "type": "object" } } } }, "401": { "description": "Missing or invalid token" }, "422": { "description": "Validation Error" }, "429": { "description": "Too Many Requests" } }, "security": [ { "sanctum": [] } ] } }, "/v1/analytics/journey/{hiveId}": { "get": { "tags": [ "Conversions" ], "summary": "Get Customer Journey", "description": "Get customer journey for a hive_id.", "operationId": "afc9d7ee0157c3d626cf5abccce274cd", "parameters": [ { "name": "hiveId", "in": "path", "description": "The Click ID to retrieve journey for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chronological timeline of visits and conversions", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "event_type": { "type": "string", "example": "click" }, "timestamp": { "type": "string", "format": "date-time" }, "url": { "type": "string" }, "country": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Missing or invalid token" }, "404": { "description": "No journey found for hive_id" } }, "security": [ { "sanctum": [] } ] } }, "/v1/link-lists": { "get": { "tags": [ "Link Lists" ], "summary": "List Link Lists", "description": "Get all link lists for the current user.", "operationId": "getLinkLists", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Link Lists" ], "summary": "Create Link List", "description": "Create a new link list.", "operationId": "storeLinkList", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "slug": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "password": { "description": "Optional password", "type": "string" }, "password_enabled": { "description": "Whether password protection is active", "type": "boolean" }, "is_public": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "201": { "description": "Link list created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Limit reached" } }, "security": [ { "sanctum": [] } ] } }, "/v1/link-lists/{id}": { "get": { "tags": [ "Link Lists" ], "summary": "Get Link List", "description": "Get link list details and its items.", "operationId": "getLinkList", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Link List Not Found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Link Lists" ], "summary": "Delete Link List", "description": "Delete a link list.", "operationId": "deleteLinkList", "responses": { "200": { "description": "Link list deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Link List Not Found" } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Link Lists" ], "summary": "Update Link List", "description": "Update an existing link list.", "operationId": "updateLinkList", "responses": { "200": { "description": "Link list updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Link List Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/link-lists/{id}/stats": { "get": { "tags": [ "Link Lists" ], "summary": "Get Link List Stats", "description": "Get analytics statistics for a specific link list.", "operationId": "getLinkListStats", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Link List Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/link-lists/{id}/export": { "get": { "tags": [ "Link Lists" ], "summary": "Export Link List Stats", "description": "Export analytics data for a specific link list as CSV.", "operationId": "exportLinkListStats", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "CSV file download" }, "404": { "description": "Link List Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/link-lists/items/{itemId}/stats": { "get": { "tags": [ "Link Lists" ], "summary": "Get Link List Item Stats", "description": "Get analytics statistics for a specific link list item.", "operationId": "getLinkListItemStats", "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Item Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/link-lists/{id}/items": { "post": { "tags": [ "Link Lists" ], "summary": "Add List Item", "description": "Add a new link to a link list.", "operationId": "addLinkListItem", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "url" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "url": { "type": "string", "format": "url", "maxLength": 2048 }, "description": { "type": "string", "maxLength": 500 }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "201": { "description": "Item added successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Item limit reached" }, "404": { "description": "Link List Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/link-lists/items/{itemId}": { "delete": { "tags": [ "Link Lists" ], "summary": "Delete List Item", "description": "Remove a link from a list.", "operationId": "deleteLinkListItem", "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Item deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Item Not Found" } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Link Lists" ], "summary": "Update List Item", "description": "Update an existing link within a list.", "operationId": "updateLinkListItem", "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Item updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Item Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/link-lists/{id}/items/reorder": { "patch": { "tags": [ "Link Lists" ], "summary": "Reorder List Items", "description": "Reorder items within a link list.", "operationId": "reorderLinkListItems", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "order" ], "properties": { "order": { "type": "array", "items": { "description": "Array of Item IDs in desired order", "type": "integer" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Items reordered successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Items reordered successfully." } }, "type": "object" } } } }, "404": { "description": "Link List Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/pixels": { "get": { "tags": [ "Pixels" ], "summary": "List Pixels", "description": "Get all pixels for the current workspace.", "operationId": "getPixels", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "type": { "type": "string", "example": "facebook" }, "name": { "type": "string", "example": "My FB Pixel" }, "pixel_id": { "type": "string", "example": "123456789" }, "head_script": { "type": "string", "nullable": true }, "body_script": { "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Pixels" ], "summary": "Create Pixel", "description": "Create a new pixel.", "operationId": "storePixel", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "name" ], "properties": { "type": { "type": "string", "example": "facebook", "enum": [ "facebook", "google", "linkedin", "twitter", "pinterest", "tiktok", "custom" ] }, "name": { "type": "string", "example": "Campaign Pixel", "maxLength": 255 }, "pixel_id": { "description": "Required for non-custom types", "type": "string", "example": "1234567890", "maxLength": 255 }, "head_script": { "description": "Required for custom type", "type": "string" }, "body_script": { "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Pixel created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" }, "message": { "type": "string", "example": "Pixel created successfully." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/v1/pixels/{pixel}": { "get": { "tags": [ "Pixels" ], "summary": "Get Pixel", "description": "Get pixel details.", "operationId": "getPixel", "parameters": [ { "name": "pixel", "in": "path", "description": "ID of the pixel", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Pixels" ], "summary": "Delete Pixel", "description": "Delete a pixel.", "operationId": "deletePixel", "parameters": [ { "name": "pixel", "in": "path", "description": "ID of the pixel", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Pixel deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Pixel deleted successfully." } }, "type": "object" } } } }, "403": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Pixels" ], "summary": "Update Pixel", "description": "Update an existing pixel.", "operationId": "updatePixel", "parameters": [ { "name": "pixel", "in": "path", "description": "ID of the pixel", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "enum": [ "facebook", "google", "linkedin", "twitter", "pinterest", "tiktok", "custom" ] }, "name": { "type": "string", "maxLength": 255 }, "pixel_id": { "type": "string", "maxLength": 255 }, "head_script": { "type": "string" }, "body_script": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Pixel updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" }, "message": { "type": "string", "example": "Pixel updated successfully." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/v1/workspaces/{workspace}/roles": { "get": { "tags": [ "Roles" ], "summary": "List Workspace Roles", "description": "Display a listing of workspace roles.", "operationId": "63a306a85d9e76dad53299d0216f9acd", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of workspace roles", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Custom Editor" }, "permissions": { "type": "array", "items": { "type": "string" } }, "is_custom": { "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Roles" ], "summary": "Create Workspace Role", "description": "Store a newly created role.", "operationId": "eed796bc78ac778217ac30e3bcacce38", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Custom Editor", "maxLength": 50 }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "view_links", "create_links" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Role created successfully" }, "403": { "description": "Unauthorized" }, "422": { "description": "Validation Error" } }, "security": [ { "sanctum": [] } ] } }, "/v1/workspaces/{workspace}/roles/{role}": { "delete": { "tags": [ "Roles" ], "summary": "Delete Workspace Role", "description": "Remove the specified role.", "operationId": "a1e138ec176247235f25523b4778729d", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Role deleted successfully" }, "403": { "description": "Unauthorized" }, "409": { "description": "Cannot delete role with assigned users" } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Roles" ], "summary": "Update Workspace Role", "description": "Update the specified role.", "operationId": "2d205f6233f41df2b906a40d8ecee4d6", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 50 }, "permissions": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Role updated successfully" }, "403": { "description": "Unauthorized" }, "404": { "description": "Role Not Found" }, "422": { "description": "Validation Error" } }, "security": [ { "sanctum": [] } ] } }, "/v1/user/theme": { "patch": { "tags": [ "User Preferences" ], "summary": "Update User Theme", "description": "Update user theme preference.", "operationId": "48a451e8e322d097aa1f6f2a7739a65e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "theme": { "type": "string", "example": "dark", "enum": [ "light", "dark", "auto", "system" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Theme updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "theme": { "type": "string", "example": "dark" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation Error" } }, "security": [ { "sanctum": [] } ] } }, "/v1/urls": { "get": { "tags": [ "URLs" ], "summary": "List all URLs", "description": "Returns a paginated list of URLs created by the authenticated user.", "operationId": "getUrlsList", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "original_url": { "type": "string", "example": "https://google.com" }, "short_code": { "type": "string", "example": "AbCd123" }, "click_count": { "type": "integer", "example": 10 }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "meta": { "properties": { "limit": { "type": "integer", "example": 50 }, "usage": { "type": "integer", "example": 5 }, "is_pro": { "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/v1/shorten": { "post": { "tags": [ "URLs" ], "summary": "Shorten a URL", "description": "Creates a shortened URL from a long URL.", "operationId": "storeUrl", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "example": "https://example.com/very/long/url" }, "custom_alias": { "description": "Optional custom alias", "type": "string", "example": "my-custom-url" }, "title": { "description": "Optional title", "type": "string", "example": "My Custom Title" }, "password": { "description": "Optional password", "type": "string" }, "password_enabled": { "description": "Whether password protection is active", "type": "boolean" }, "expires_at": { "description": "Optional expiration date", "type": "string", "format": "date-time" } }, "type": "object" } } } }, "responses": { "201": { "description": "URL Created Successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer", "example": 12 }, "short_url": { "type": "string", "example": "https://urlhive.net/AbCd12" }, "short_code": { "type": "string", "example": "AbCd12" }, "original_url": { "type": "string", "example": "https://example.com/very/long/url" }, "is_password_protected": { "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation Error" }, "429": { "description": "Too Many Requests" } }, "security": [ { "sanctum": [] } ] } }, "/v1/urls/{shortCode}": { "get": { "tags": [ "URLs" ], "summary": "Get URL Details", "description": "Returns details of a specific URL.", "operationId": "getUrl", "parameters": [ { "name": "shortCode", "in": "path", "description": "Short code of the URL", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "original_url": { "type": "string", "example": "https://google.com" }, "short_code": { "type": "string", "example": "AbCd123" }, "click_count": { "type": "integer", "example": 150 }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "URL Not Found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "URLs" ], "summary": "Delete a URL", "description": "Deletes a specific URL.", "operationId": "deleteUrl", "parameters": [ { "name": "shortCode", "in": "path", "description": "Short code of the URL", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "URL deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "URL deleted successfully." } }, "type": "object" } } } }, "404": { "description": "URL Not Found" } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "URLs" ], "summary": "Update a URL", "description": "Updates an existing short URL and its variants.", "operationId": "updateUrl", "parameters": [ { "name": "shortCode", "in": "path", "description": "Short code of the URL", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "example": "https://example.com/new/url" }, "custom_alias": { "description": "Optional custom alias", "type": "string", "example": "new-alias" }, "title": { "description": "Optional title", "type": "string", "example": "Updated Title" }, "password": { "description": "Optional password", "type": "string" }, "password_enabled": { "description": "Whether password protection is active", "type": "boolean" }, "expires_at": { "description": "Optional expiration date", "type": "string", "format": "date-time" }, "variants": { "type": "array", "items": { "properties": { "url": { "type": "string", "format": "url" }, "weight": { "type": "integer" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "URL Updated Successfully" }, "404": { "description": "URL Not Found" }, "422": { "description": "Validation Error" } }, "security": [ { "sanctum": [] } ] } }, "/v1/urls/{shortCode}/stats": { "get": { "tags": [ "URLs" ], "summary": "Get URL Statistics", "description": "Returns analytics for a specific URL.", "operationId": "getUrlStats", "parameters": [ { "name": "shortCode", "in": "path", "description": "Short code of the URL", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "clicks_over_time": { "type": "array", "items": { "type": "object" } }, "countries": { "type": "array", "items": { "type": "object" } }, "referrers": { "type": "array", "items": { "type": "object" } }, "devices": { "type": "array", "items": { "type": "object" } }, "browsers": { "type": "array", "items": { "type": "object" } }, "os": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "URL Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/urls/{shortCode}/conversions": { "get": { "tags": [ "URLs" ], "summary": "Get URL Conversions", "description": "Returns detailed conversion analytics for a specific URL.", "operationId": "getUrlConversions", "responses": { "200": { "description": "Conversion analytics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Conversion analytics data", "type": "object" } }, "type": "object" } } } }, "403": { "description": "Feature locked or unauthorized" }, "404": { "description": "URL Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/urls/{shortCode}/toggle": { "patch": { "tags": [ "URLs" ], "summary": "Toggle URL Status", "description": "Enable or disable a URL.", "operationId": "toggleUrl", "parameters": [ { "name": "shortCode", "in": "path", "description": "Short code of the URL", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status toggled successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "is_active": { "type": "boolean", "example": false } }, "type": "object" } } } }, "404": { "description": "URL Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/urls/{shortCode}/export": { "get": { "tags": [ "URLs" ], "summary": "Export Usage Stats", "description": "Downloads a CSV file of the URL analytics.", "operationId": "exportUrlStats", "parameters": [ { "name": "shortCode", "in": "path", "description": "Short code of the URL", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV File Download", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "URL Not Found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/urls/bulk": { "post": { "tags": [ "URLs" ], "summary": "Bulk Import URLs", "description": "Import multiple URLs from a CSV file.", "operationId": "bulkCreateUrls", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "CSV file to import", "type": "string", "format": "binary" }, "skip_duplicates": { "description": "Skip duplicate URLs", "type": "boolean" }, "create_short_codes": { "description": "Create short codes for imported URLs", "type": "boolean" }, "workspace_id": { "description": "Target workspace ID", "type": "integer" } }, "type": "object" } } } }, "responses": { "202": { "description": "Import job accepted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Import job queued" }, "data": { "properties": { "job_id": { "type": "string", "example": "uuid" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation Error" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "URLs" ], "summary": "Bulk Delete URLs", "description": "Delete multiple URLs.", "operationId": "bulkDeleteUrls", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "ids": { "description": "URL IDs to delete", "type": "array", "items": { "type": "integer" } }, "confirm": { "description": "Confirmation flag", "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Delete successful", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "URLs deleted successfully" } }, "type": "object" } } } }, "422": { "description": "Validation Error" } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "URLs" ], "summary": "Bulk Update URLs", "description": "Update multiple URLs with common fields.", "operationId": "bulkUpdateUrls", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "ids": { "description": "URL IDs to update", "type": "array", "items": { "type": "integer" } }, "title": { "description": "New title", "type": "string" }, "expires_at": { "description": "New expiration date", "type": "string", "format": "date-time" }, "is_active": { "description": "Active status", "type": "boolean" }, "conversion_tracking_enabled": { "description": "Conversion tracking status", "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Update successful", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "URLs updated successfully" }, "data": { "properties": { "updated_count": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation Error" } }, "security": [ { "sanctum": [] } ] } }, "/v1/urls/bulk/export": { "get": { "tags": [ "URLs" ], "summary": "Bulk Export URLs", "description": "Export multiple URLs to CSV format.", "operationId": "bulkExportUrls", "parameters": [ { "name": "ids", "in": "query", "description": "Comma-separated URL IDs to export", "required": false, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Export format", "required": true, "schema": { "type": "string", "enum": [ "csv", "xlsx" ] } }, { "name": "include_analytics", "in": "query", "description": "Include analytics data", "required": false, "schema": { "type": "boolean" } }, { "name": "start_date", "in": "query", "description": "Start date for filtering", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "End date for filtering", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "CSV File Download", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "422": { "description": "Validation Error" } }, "security": [ { "sanctum": [] } ] } }, "/v1/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List Workspaces", "description": "Get all workspaces the user belongs to.", "operationId": "getWorkspaces", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Workspace" }, "slug": { "type": "string", "example": "my-workspace" }, "owner_id": { "type": "integer", "example": 1 } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Workspaces" ], "summary": "Create Workspace", "description": "Create a new workspace.", "operationId": "storeWorkspace", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Production", "maxLength": 50 }, "slug": { "type": "string", "example": "production", "maxLength": 50 } }, "type": "object" } } } }, "responses": { "201": { "description": "Workspace created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" }, "message": { "type": "string", "example": "Workspace created successfully." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/v1/workspaces/{workspace}/switch": { "post": { "tags": [ "Workspaces" ], "summary": "Switch Workspace", "description": "Switch current workspace.", "operationId": "switchWorkspace", "parameters": [ { "name": "workspace", "in": "path", "description": "ID of the workspace", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Switched to workspace", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" }, "message": { "type": "string", "example": "Switched to workspace: Production" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/v1/workspaces/{workspace}": { "get": { "tags": [ "Workspaces" ], "summary": "Get Workspace", "description": "Get workspace details including members and stats.", "operationId": "showWorkspace", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Workspaces" ], "summary": "Update Workspace", "description": "Update workspace details.", "operationId": "updateWorkspace", "parameters": [ { "name": "workspace", "in": "path", "description": "ID of the workspace", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 50 }, "slug": { "type": "string", "maxLength": 50 } }, "type": "object" } } } }, "responses": { "200": { "description": "Workspace updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" }, "message": { "type": "string", "example": "Workspace updated successfully." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete Workspace", "description": "Delete a workspace. Only the owner can delete a workspace.", "operationId": "destroyWorkspace", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Workspace deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workspace deleted successfully." } }, "type": "object" } } } }, "403": { "description": "Only owner can delete" } }, "security": [ { "sanctum": [] } ] } }, "/v1/workspaces/{workspace}/members": { "get": { "tags": [ "Workspaces" ], "summary": "Get Members", "description": "Get workspace members.", "operationId": "getWorkspaceMembers", "parameters": [ { "name": "workspace", "in": "path", "description": "ID of the workspace", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "role": { "type": "string", "example": "owner" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/v1/workspaces/{workspace}/invitations": { "post": { "tags": [ "Workspaces" ], "summary": "Invite Member", "description": "Invite a user to join the workspace by email.", "operationId": "inviteWorkspaceMember", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "role": { "type": "string", "example": "editor", "enum": [ "admin", "editor", "viewer" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Invitation sent" }, "403": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/v1/workspaces/invitations/{invitation}": { "delete": { "tags": [ "Workspaces" ], "summary": "Cancel Invitation", "description": "Cancel a pending workspace invitation.", "operationId": "cancelWorkspaceInvitation", "parameters": [ { "name": "invitation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Invitation cancelled" }, "404": { "description": "Invitation not found" } }, "security": [ { "sanctum": [] } ] } }, "/v1/workspaces/{workspace}/members/{user}": { "delete": { "tags": [ "Workspaces" ], "summary": "Remove Member", "description": "Remove a member from the workspace. Only owners and admins can remove members.", "operationId": "removeWorkspaceMember", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Member removed" }, "403": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } } }, "components": { "securitySchemes": { "sanctum": { "type": "http", "description": "Login with email and password to get the authentication token", "name": "API Token", "in": "header", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Conversions", "description": "Server-to-server conversion tracking and customer journey analytics" }, { "name": "Roles", "description": "Workspace role management (Enterprise only)" }, { "name": "User Preferences", "description": "User personalization settings" }, { "name": "Bio Links", "description": "Bio Links" }, { "name": "Bio Pages", "description": "Bio Pages" }, { "name": "Link Lists", "description": "Link Lists" }, { "name": "Pixels", "description": "Pixels" }, { "name": "URLs", "description": "URLs" }, { "name": "Workspaces", "description": "Workspaces" } ] }