{ "openapi": "3.0.3", "info": { "title": "Goose.re API", "version": "1.1.0", "description": "OpenAPI specification for the Goose.re endpoints documented on `/docs/api`. This document favors the backend's actual request and response shapes where earlier prose examples used simplified field names.", "contact": { "name": "Goose.re Support", "email": "support@goose.re" } }, "servers": [ { "url": "https://api.goose.re/api/v1", "description": "Production API" } ], "tags": [ { "name": "Links", "description": "Short link creation, retrieval, updates, and deletion." }, { "name": "Bio Pages", "description": "Link-in-bio pages, page links, plugins, and ordering." }, { "name": "Analytics", "description": "Team-level analytics and segmentation data." }, { "name": "QR Codes", "description": "QR code creation and management." }, { "name": "Folders", "description": "Team folders used to organize links, pages, and QR codes." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/links": { "get": { "tags": [ "Links" ], "summary": "List links", "operationId": "listLinks", "description": "Returns a paginated list of links for the active team context.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "search", "in": "query", "description": "Filter by short code, destination URL, or title.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "description": "Filter by active state.", "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "name": "folder_id", "in": "query", "description": "Filter links within a specific folder.", "schema": { "type": "string", "format": "uuid" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "created_at", "short_url", "total_clicks" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Paginated list of links.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Links" ], "summary": "Create link", "operationId": "createLink", "description": "Creates a short link. The implementation expects `url` and optional `custom_slug`. Earlier prose docs that used `destination` and `slug` were illustrative, not literal request keys.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkCreateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LinkCreateRequest" } } } }, "responses": { "201": { "description": "Link created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/links/{id}": { "get": { "tags": [ "Links" ], "summary": "Get link", "operationId": "getLink", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Link details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "tags": [ "Links" ], "summary": "Update link", "operationId": "updateLink", "description": "Updates a link. Use `destination_url` to change the target URL.", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkUpdateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/LinkUpdateRequest" } } } }, "responses": { "200": { "description": "Updated link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "tags": [ "Links" ], "summary": "Delete link", "operationId": "deleteLink", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Deletion acknowledged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptySuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pages": { "get": { "tags": [ "Bio Pages" ], "summary": "List bio pages", "operationId": "listBioPages", "parameters": [ { "name": "folder_id", "in": "query", "description": "Filter by folder UUID. Pass an empty string to show pages without a folder.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "created_at", "title", "slug", "total_clicks" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "List of bio pages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioPageListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Bio Pages" ], "summary": "Create bio page", "operationId": "createBioPage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioPageCreateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BioPageCreateRequest" } } } }, "responses": { "201": { "description": "Bio page created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioPageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pages/{id}": { "get": { "tags": [ "Bio Pages" ], "summary": "Get bio page", "operationId": "getBioPage", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Bio page details with nested page links and plugins.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioPageDetailResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "tags": [ "Bio Pages" ], "summary": "Update bio page", "operationId": "updateBioPage", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioPageUpdateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BioPageUpdateRequest" } } } }, "responses": { "200": { "description": "Updated bio page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioPageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "tags": [ "Bio Pages" ], "summary": "Delete bio page", "operationId": "deleteBioPage", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Deletion acknowledged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptySuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pages/{id}/links": { "post": { "tags": [ "Bio Pages" ], "summary": "Add bio link", "operationId": "addBioPageLink", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioLinkCreateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BioLinkCreateRequest" } } } }, "responses": { "201": { "description": "Bio link created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioLinkResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pages/{id}/links/{linkId}": { "put": { "tags": [ "Bio Pages" ], "summary": "Update bio link", "operationId": "updateBioPageLink", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/LinkId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioLinkUpdateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BioLinkUpdateRequest" } } } }, "responses": { "200": { "description": "Updated bio link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioLinkResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "tags": [ "Bio Pages" ], "summary": "Delete bio link", "operationId": "deleteBioPageLink", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/LinkId" } ], "responses": { "200": { "description": "Deletion acknowledged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptySuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pages/{id}/plugins": { "post": { "tags": [ "Bio Pages" ], "summary": "Add bio plugin", "operationId": "addBioPagePlugin", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioPluginCreateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BioPluginCreateRequest" } } } }, "responses": { "201": { "description": "Bio plugin created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioPluginResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pages/{id}/plugins/{pluginId}": { "put": { "tags": [ "Bio Pages" ], "summary": "Update bio plugin", "operationId": "updateBioPagePlugin", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/PluginId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioPluginUpdateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BioPluginUpdateRequest" } } } }, "responses": { "200": { "description": "Updated bio plugin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BioPluginResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "tags": [ "Bio Pages" ], "summary": "Delete bio plugin", "operationId": "deleteBioPagePlugin", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/PluginId" } ], "responses": { "200": { "description": "Deletion acknowledged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptySuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pages/{id}/reorder": { "post": { "tags": [ "Bio Pages" ], "summary": "Reorder bio page items", "operationId": "reorderBioPageItems", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ReorderRequest" } } } }, "responses": { "200": { "description": "Order saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptySuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/analytics": { "get": { "tags": [ "Analytics" ], "summary": "Get analytics", "operationId": "getAnalytics", "description": "Returns team-level analytics. The implementation currently filters by relative `period` and optional `link_id`, `folder_id`, `tag_id`, and `builder` filters.", "parameters": [ { "name": "link_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "folder_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "tag_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "query", "description": "Relative reporting window.", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d", "all" ], "default": "30d" } }, { "name": "builder", "in": "query", "description": "JSON-encoded advanced filter builder array.", "schema": { "type": "string", "example": "[{\"field\":\"browser\",\"operator\":\"is\",\"values\":[\"Chrome\"]}]" } } ], "responses": { "200": { "description": "Aggregated analytics payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/qrcodes": { "get": { "tags": [ "QR Codes" ], "summary": "List QR codes", "operationId": "listQrCodes", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "search", "in": "query", "description": "Filter by QR code name, short code, or destination URL.", "schema": { "type": "string" } }, { "name": "folder_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "created_at", "name", "short_url", "total_clicks" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Paginated list of QR codes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "QR Codes" ], "summary": "Create QR code", "operationId": "createQrCode", "description": "Creates a QR code. Provide either `link_id` or `url`. If only `url` is provided, Goose.re creates a short link automatically.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeCreateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/QrCodeCreateRequest" } } } }, "responses": { "201": { "description": "QR code created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/qrcodes/{id}": { "get": { "tags": [ "QR Codes" ], "summary": "Get QR code", "operationId": "getQrCode", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "QR code details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "tags": [ "QR Codes" ], "summary": "Update QR code", "operationId": "updateQrCode", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeUpdateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/QrCodeUpdateRequest" } } } }, "responses": { "200": { "description": "Updated QR code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "tags": [ "QR Codes" ], "summary": "Delete QR code", "operationId": "deleteQrCode", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Deletion acknowledged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptySuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/folders": { "get": { "tags": [ "Folders" ], "summary": "List folders", "operationId": "listFolders", "responses": { "200": { "description": "Folder collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Folders" ], "summary": "Create folder", "operationId": "createFolder", "description": "Creates a folder. Team owner or admin permissions are required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderCreateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FolderCreateRequest" } } } }, "responses": { "201": { "description": "Folder created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "LinkId": { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "PluginId": { "name": "pluginId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "Offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } }, "responses": { "Unauthorized": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Authenticated, but not allowed to perform the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Validation or business rule failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequests": { "description": "Rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "SuccessMeta": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" } } }, "ErrorResponse": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "TimestampString": { "type": "string", "description": "Timestamp string returned by the current API implementation.", "example": "2026-07-04 22:19:50" }, "ColorHex": { "type": "string", "pattern": "^#[0-9A-Fa-f]{3}([0-9A-Fa-f]{3})?$", "example": "#4f46e5" }, "Tag": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "$ref": "#/components/schemas/ColorHex" } } }, "LinkAbTest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "link_id": { "type": "string", "format": "uuid" }, "destination_url": { "type": "string", "format": "uri" }, "weight": { "type": "integer" } } }, "LinkTargetingRule": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "link_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "value": { "type": "string" }, "destination_url": { "type": "string", "format": "uri" } } }, "Link": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "team_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "folder_id": { "type": "string", "format": "uuid", "nullable": true }, "domain_id": { "type": "string", "format": "uuid", "nullable": true }, "short_code": { "type": "string" }, "destination_url": { "type": "string", "format": "uri" }, "title": { "type": "string", "nullable": true }, "redirect_type": { "type": "string", "enum": [ "screen", "instant", "password" ] }, "is_active": { "type": "integer", "enum": [ 0, 1 ] }, "expires_at": { "$ref": "#/components/schemas/TimestampString" }, "meta_title": { "type": "string", "nullable": true }, "meta_description": { "type": "string", "nullable": true }, "meta_image": { "type": "string", "format": "uri", "nullable": true }, "ab_test_url": { "type": "string", "format": "uri", "nullable": true }, "ab_test_percentage": { "type": "integer" }, "total_clicks": { "type": "integer" }, "created_at": { "$ref": "#/components/schemas/TimestampString" }, "updated_at": { "$ref": "#/components/schemas/TimestampString" }, "short_url": { "type": "string", "format": "uri" }, "custom_domain": { "type": "string", "nullable": true }, "creator_username": { "type": "string", "nullable": true }, "folder_name": { "type": "string", "nullable": true }, "folder_color": { "type": "string", "nullable": true }, "folder_icon": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "ab_tests": { "type": "array", "items": { "$ref": "#/components/schemas/LinkAbTest" } }, "targeting": { "type": "array", "items": { "$ref": "#/components/schemas/LinkTargetingRule" } } } }, "LinkListData": { "type": "object", "required": [ "links", "total" ], "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }, "total": { "type": "integer" } } }, "LinkCreateRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Destination URL for the new short link." }, "custom_slug": { "type": "string", "description": "Custom short code. Must be unique per domain." }, "domain_id": { "type": "string", "format": "uuid" }, "folder_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "redirect_type": { "type": "string", "enum": [ "screen", "instant", "password" ], "default": "screen" }, "password": { "type": "string" }, "expires_at": { "$ref": "#/components/schemas/TimestampString" }, "meta_title": { "type": "string" }, "meta_description": { "type": "string" }, "meta_image": { "type": "string", "format": "uri" }, "ab_test_url": { "type": "string", "format": "uri" }, "ab_test_percentage": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "ab_tests": { "type": "array", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "weight": { "type": "integer", "default": 50 } } } }, "targeting": { "type": "array", "items": { "type": "object", "required": [ "type", "value", "url" ], "properties": { "type": { "type": "string" }, "value": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } }, "example": { "url": "https://example.com/very-long-url-path-here", "custom_slug": "my-promo", "folder_id": "9a60e0a5-2962-4217-ba5c-0b92db2c92be", "title": "Summer Promo Link" } }, "LinkUpdateRequest": { "type": "object", "properties": { "title": { "type": "string" }, "destination_url": { "type": "string", "format": "uri" }, "redirect_type": { "type": "string", "enum": [ "screen", "instant", "password" ] }, "password": { "type": "string" }, "is_active": { "type": "integer", "enum": [ 0, 1 ] }, "expires_at": { "$ref": "#/components/schemas/TimestampString" }, "folder_id": { "type": "string", "format": "uuid", "nullable": true }, "meta_title": { "type": "string" }, "meta_description": { "type": "string" }, "meta_image": { "type": "string", "format": "uri" }, "ab_test_url": { "type": "string", "format": "uri" }, "ab_test_percentage": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "ab_tests": { "type": "array", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "weight": { "type": "integer", "default": 50 } } } }, "targeting": { "type": "array", "items": { "type": "object", "required": [ "type", "value", "url" ], "properties": { "type": { "type": "string" }, "value": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } }, "example": { "destination_url": "https://new-destination.com/page", "title": "Updated Campaign URL" } }, "BioLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "page_id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "icon": { "type": "string" }, "color": { "$ref": "#/components/schemas/ColorHex" }, "bg_color": { "$ref": "#/components/schemas/ColorHex" }, "animation": { "type": "string" }, "sort_order": { "type": "integer" }, "clicks": { "type": "integer" }, "created_at": { "$ref": "#/components/schemas/TimestampString" } } }, "BioPlugin": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "page_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "config": { "type": "object", "additionalProperties": true }, "sort_order": { "type": "integer" }, "created_at": { "$ref": "#/components/schemas/TimestampString" } } }, "BioPage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "team_id": { "type": "string", "format": "uuid" }, "folder_id": { "type": "string", "format": "uuid", "nullable": true }, "domain_id": { "type": "string", "format": "uuid", "nullable": true }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "profile_image": { "type": "string", "format": "uri", "nullable": true }, "background_image": { "type": "string", "format": "uri", "nullable": true }, "favicon": { "type": "string", "format": "uri", "nullable": true }, "theme": { "type": "string" }, "theme_accent_1": { "$ref": "#/components/schemas/ColorHex" }, "theme_accent_2": { "$ref": "#/components/schemas/ColorHex" }, "custom_css": { "type": "string", "nullable": true }, "folder_name": { "type": "string", "nullable": true }, "folder_color": { "type": "string", "nullable": true }, "folder_icon": { "type": "string", "nullable": true }, "total_clicks": { "type": "integer" }, "link_count": { "type": "integer" }, "plugin_count": { "type": "integer" }, "created_at": { "$ref": "#/components/schemas/TimestampString" }, "updated_at": { "$ref": "#/components/schemas/TimestampString" } } }, "BioPageDetail": { "allOf": [ { "$ref": "#/components/schemas/BioPage" }, { "type": "object", "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/BioLink" } }, "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/BioPlugin" } } } } ] }, "BioPageCreateRequest": { "type": "object", "required": [ "slug", "title" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "theme": { "type": "string", "default": "default" }, "theme_accent_1": { "$ref": "#/components/schemas/ColorHex" }, "theme_accent_2": { "$ref": "#/components/schemas/ColorHex" }, "domain_id": { "type": "string", "format": "uuid" }, "folder_id": { "type": "string", "format": "uuid" } }, "example": { "slug": "developer-advocacy", "title": "Developer Relations Resources", "description": "Find official Goose.re developer resources.", "theme": "glass", "theme_accent_1": "#6366f1" } }, "BioPageUpdateRequest": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "profile_image": { "type": "string", "format": "uri" }, "background_image": { "type": "string", "format": "uri" }, "favicon": { "type": "string", "format": "uri" }, "theme": { "type": "string" }, "theme_accent_1": { "$ref": "#/components/schemas/ColorHex" }, "theme_accent_2": { "$ref": "#/components/schemas/ColorHex" }, "custom_css": { "type": "string" }, "domain_id": { "type": "string", "format": "uuid", "nullable": true }, "folder_id": { "type": "string", "format": "uuid", "nullable": true } } }, "BioLinkCreateRequest": { "type": "object", "required": [ "label", "url" ], "properties": { "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "icon": { "type": "string" }, "color": { "$ref": "#/components/schemas/ColorHex" }, "bg_color": { "$ref": "#/components/schemas/ColorHex" }, "animation": { "type": "string", "default": "none" }, "sort_order": { "type": "integer", "default": 0 } } }, "BioLinkUpdateRequest": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "icon": { "type": "string" }, "color": { "$ref": "#/components/schemas/ColorHex" }, "bg_color": { "$ref": "#/components/schemas/ColorHex" }, "animation": { "type": "string" }, "sort_order": { "type": "integer" } } }, "BioPluginCreateRequest": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "config": { "type": "object", "additionalProperties": true }, "sort_order": { "type": "integer", "default": 0 } } }, "BioPluginUpdateRequest": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": true }, "sort_order": { "type": "integer" } } }, "ReorderItem": { "type": "object", "required": [ "id", "type", "sort_order" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "link", "plugin" ] }, "sort_order": { "type": "integer" } } }, "ReorderRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReorderItem" } } } }, "NamedCount": { "type": "object", "properties": { "name": { "type": "string" }, "count": { "type": "integer" } } }, "TimeSeriesPoint": { "type": "object", "properties": { "date": { "type": "string", "example": "2026-07-04" }, "count": { "type": "integer" } } }, "RecentClick": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "link_id": { "type": "string", "format": "uuid", "nullable": true }, "page_id": { "type": "string", "format": "uuid", "nullable": true }, "bio_link_id": { "type": "string", "format": "uuid", "nullable": true }, "user_agent": { "type": "string" }, "referer": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true }, "subnet": { "type": "string", "nullable": true }, "visitor_id": { "type": "string" }, "device_type": { "type": "string" }, "browser": { "type": "string" }, "os": { "type": "string" }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true }, "utm_term": { "type": "string", "nullable": true }, "utm_content": { "type": "string", "nullable": true }, "clicked_at": { "$ref": "#/components/schemas/TimestampString" }, "short_code": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "destination_url": { "type": "string", "nullable": true } } }, "AnalyticsStats": { "type": "object", "properties": { "total_clicks": { "type": "integer" }, "unique_visitors": { "type": "integer" }, "avg_clicks": { "type": "number" }, "top_referrer": { "type": "string" } } }, "AnalyticsData": { "type": "object", "properties": { "timeSeries": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesPoint" } }, "browsers": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } }, "os": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } }, "languages": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } }, "subnets": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } }, "referrers": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } }, "topLinks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "short_code": { "type": "string" }, "title": { "type": "string", "nullable": true }, "destination_url": { "type": "string" }, "count": { "type": "integer" } } } }, "topDestinations": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } }, "utm": { "type": "object", "properties": { "source": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } }, "medium": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } }, "campaign": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } }, "term": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/NamedCount" } } } }, "recentClicks": { "type": "array", "items": { "$ref": "#/components/schemas/RecentClick" } }, "stats": { "$ref": "#/components/schemas/AnalyticsStats" } } }, "QrCode": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "team_id": { "type": "string", "format": "uuid" }, "link_id": { "type": "string", "format": "uuid" }, "folder_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "design_config": { "type": "object", "additionalProperties": true }, "short_code": { "type": "string", "nullable": true }, "short_url": { "type": "string", "format": "uri" }, "custom_domain": { "type": "string", "nullable": true }, "folder_name": { "type": "string", "nullable": true }, "folder_color": { "type": "string", "nullable": true }, "folder_icon": { "type": "string", "nullable": true }, "total_clicks": { "type": "integer", "nullable": true }, "created_at": { "$ref": "#/components/schemas/TimestampString" }, "updated_at": { "$ref": "#/components/schemas/TimestampString" } } }, "QrCodeListData": { "type": "object", "required": [ "qrcodes", "total" ], "properties": { "qrcodes": { "type": "array", "items": { "$ref": "#/components/schemas/QrCode" } }, "total": { "type": "integer" } } }, "QrCodeCreateRequest": { "type": "object", "required": [ "name", "design_config" ], "properties": { "name": { "type": "string" }, "design_config": { "description": "Either an object or a JSON string; the API accepts both.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string" } ] }, "url": { "type": "string", "format": "uri" }, "link_id": { "type": "string", "format": "uuid" }, "folder_id": { "type": "string", "format": "uuid" } }, "example": { "name": "Event Banner QR", "design_config": { "color": "#1d4ed8", "bg_color": "#ffffff" }, "url": "https://example.com/event-registration" } }, "QrCodeUpdateRequest": { "type": "object", "properties": { "name": { "type": "string" }, "design_config": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string" } ] }, "link_id": { "type": "string", "format": "uuid" }, "folder_id": { "type": "string", "format": "uuid", "nullable": true } } }, "Folder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "team_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "$ref": "#/components/schemas/ColorHex" }, "icon": { "type": "string" }, "created_at": { "$ref": "#/components/schemas/TimestampString" } } }, "FolderCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "color": { "$ref": "#/components/schemas/ColorHex" }, "icon": { "type": "string" } }, "example": { "name": "Marketing Campaigns", "color": "#3B82F6", "icon": "fa-folder" } }, "LinkResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Link" } } } ] }, "LinkListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LinkListData" } } } ] }, "BioPageResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BioPage" } } } ] }, "BioPageDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BioPageDetail" } } } ] }, "BioPageListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BioPage" } } } } ] }, "BioLinkResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BioLink" } } } ] }, "BioPluginResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BioPlugin" } } } ] }, "AnalyticsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AnalyticsData" } } } ] }, "QrCodeResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/QrCode" } } } ] }, "QrCodeListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/QrCodeListData" } } } ] }, "FolderResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Folder" } } } ] }, "FolderListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Folder" } } } } ] }, "EmptySuccessResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true, "nullable": true } } } ], "example": { "success": true, "message": "Deleted successfully", "data": null } } } } }