{ "openapi": "3.1.0", "info": { "title": "Ruby Developer API", "description": "Official public REST API for the Ruby Enterprise URL Shortener platform. Create, manage, and analyze branded short links and bulk campaigns programmatically.", "version": "v1" }, "servers": [ { "url": "https://api.rby.one", "description": "Production API Server" } ], "paths": { "/v1/health": { "get": { "tags": [ "System" ], "summary": "Api V1 Health Check", "operationId": "api_v1_health_check_v1_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/links": { "post": { "tags": [ "Developer API - Links" ], "summary": "Create Link", "description": "Creates a new short link for the authenticated organization.", "operationId": "create_link_v1_links_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLinkApiRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkApiResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Developer API - Links" ], "summary": "List Links", "description": "Lists short links for the authenticated organization with cursor pagination.\nSupports filtering by domain, is_active, group_public_id, and keyword search.", "operationId": "list_links_v1_links_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "group_public_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group Public Id" } }, { "name": "domain", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain" } }, { "name": "is_active", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_LinkApiResponse_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/links/lookup": { "get": { "tags": [ "Developer API - Links" ], "summary": "Lookup Link", "description": "Reverse lookup for a short link by domain and short code.", "operationId": "lookup_link_v1_links_lookup_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string", "description": "Short domain (e.g. 'rby.one')", "title": "Domain" }, "description": "Short domain (e.g. 'rby.one')" }, { "name": "short_code", "in": "query", "required": true, "schema": { "type": "string", "description": "Short code (e.g. 'summer26')", "title": "Short Code" }, "description": "Short code (e.g. 'summer26')" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkApiResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/links/{public_id}": { "get": { "tags": [ "Developer API - Links" ], "summary": "Get Link", "description": "Retrieves short link details by its public ID.", "operationId": "get_link_v1_links__public_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkApiResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Developer API - Links" ], "summary": "Update Link", "description": "Updates short link destination, metadata, or status.", "operationId": "update_link_v1_links__public_id__put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLinkApiRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkApiResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Developer API - Links" ], "summary": "Delete Link", "description": "Deactivates (soft delete) or purges (hard delete) a short link.", "operationId": "delete_link_v1_links__public_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } }, { "name": "hard", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If true, permanently purges entity from Datastore. Default is soft deactivation.", "default": false, "title": "Hard" }, "description": "If true, permanently purges entity from Datastore. Default is soft deactivation." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/links/{public_id}/stats": { "get": { "tags": [ "Developer API - Links" ], "summary": "Get Link Analytics", "description": "Retrieves analytics metrics and breakdowns for a short link.", "operationId": "get_link_analytics_v1_links__public_id__stats_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } }, { "name": "period", "in": "query", "required": false, "schema": { "enum": [ 7, 30, 60, 90, 180, 365, 730, 1825 ], "type": "integer", "default": 30, "title": "Period" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsStatsResponseSchema" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/groups": { "post": { "tags": [ "Developer API - Link Groups" ], "summary": "Create Group", "description": "Creates a new link group / campaign for the authenticated organization.", "operationId": "create_group_v1_groups_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupApiRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupApiResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Developer API - Link Groups" ], "summary": "List Groups", "description": "Lists link groups for the active organization with cursor pagination.", "operationId": "list_groups_v1_groups_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to include inactive (soft-deleted) groups", "default": false, "title": "Include Inactive" }, "description": "Whether to include inactive (soft-deleted) groups" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search groups by title", "title": "Search" }, "description": "Search groups by title" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_GroupApiResponse_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/groups/{public_id}": { "get": { "tags": [ "Developer API - Link Groups" ], "summary": "Get Group", "description": "Retrieves link group details by public_id.", "operationId": "get_group_v1_groups__public_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupApiResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Developer API - Link Groups" ], "summary": "Update Group", "description": "Updates group title or description.", "operationId": "update_group_v1_groups__public_id__put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGroupApiRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupApiResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Developer API - Link Groups" ], "summary": "Delete Group", "description": "Deactivates (soft delete) or purges (hard delete) a link group and all associated links.\n- Soft delete (hard=False): Sets group.status = 'inactive' and invalidates Redis cache.\n- Hard delete (hard=True): Sets group.status = 'deleting', invalidates Redis cache,\n and starts HardDeleteGroupWorkflow.", "operationId": "delete_group_v1_groups__public_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } }, { "name": "hard", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If true, permanently purges group and all links. Default is soft-delete.", "default": false, "title": "Hard" }, "description": "If true, permanently purges group and all links. Default is soft-delete." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/groups/{public_id}/links": { "get": { "tags": [ "Developer API - Link Groups" ], "summary": "List Group Links", "description": "Lists short links belonging to the specified group with cursor pagination.", "operationId": "list_group_links_v1_groups__public_id__links_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_LinkApiResponse_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/groups/{public_id}/stats": { "get": { "tags": [ "Developer API - Link Groups" ], "summary": "Get Group Analytics", "description": "Retrieves aggregated click analytics and breakdowns for all links in a group.", "operationId": "get_group_analytics_v1_groups__public_id__stats_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } }, { "name": "period", "in": "query", "required": false, "schema": { "enum": [ 7, 30, 60, 90, 180, 365, 730, 1825 ], "type": "integer", "default": 30, "title": "Period" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsStatsResponseSchema" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/groups/{public_id}/links/batch": { "post": { "tags": [ "Developer API - Link Groups" ], "summary": "Create Links Batch", "description": "High-throughput batch link creation inside a group (up to 500 links).\nEnforces All-or-Nothing transactional consistency and plan link quotas.", "operationId": "create_links_batch_v1_groups__public_id__links_batch_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateLinksApiRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateLinksApiResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/groups/{public_id}/export": { "get": { "tags": [ "Developer API - Link Groups" ], "summary": "Export Group", "description": "Exports all links in the specified group.\n- If group is dynamic and has 0 links: generates a header-only CSV immediately and returns download URL.\n- If group is dynamic and <= 2000 links: generates CSV immediately and returns download URL.\n- If group is dynamic and > 2000 links:\n - If export is already ready (and refresh=False), returns download URL.\n - If export is not ready, triggers ExportGroupWorkflow and returns status='processing' (202).", "operationId": "export_group_v1_groups__public_id__export_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } }, { "name": "refresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Force re-generation of export for dynamic groups", "default": false, "title": "Refresh" }, "description": "Force re-generation of export for dynamic groups" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupExportApiResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/domains": { "get": { "tags": [ "Developer API - Domains" ], "summary": "List Available Domains", "description": "Returns the list of domains available for creating short links:\n1. Platform default domains (is_default=True).\n2. Active verified custom branded domains belonging to the authenticated tenant (is_default=False).", "operationId": "list_available_domains_v1_domains_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableDomainsApiResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } } }, "components": { "schemas": { "AnalyticsBreakdowns": { "properties": { "devices": { "items": { "$ref": "#/components/schemas/DistributionItem" }, "type": "array", "title": "Devices" }, "browsers": { "items": { "$ref": "#/components/schemas/DistributionItem" }, "type": "array", "title": "Browsers" }, "os": { "items": { "$ref": "#/components/schemas/DistributionItem" }, "type": "array", "title": "Os" }, "countries": { "items": { "$ref": "#/components/schemas/DistributionItem" }, "type": "array", "title": "Countries" }, "referrers": { "items": { "$ref": "#/components/schemas/DistributionItem" }, "type": "array", "title": "Referrers" } }, "type": "object", "title": "AnalyticsBreakdowns" }, "AnalyticsStatsResponseSchema": { "properties": { "total_clicks": { "type": "integer", "title": "Total Clicks", "description": "Total human clicks in period", "default": 0 }, "unique_visitors": { "type": "integer", "title": "Unique Visitors", "description": "Total unique human visitors in period", "default": 0 }, "bot_clicks": { "type": "integer", "title": "Bot Clicks", "description": "Automated bot/crawler clicks detected", "default": 0 }, "period": { "type": "string", "title": "Period", "description": "Selected time range", "default": "30d" }, "interval": { "type": "string", "title": "Interval", "description": "Granularity of the time series points ('day' or 'week')", "default": "day" }, "start_date": { "type": "string", "title": "Start Date", "description": "ISO formatted start date of range" }, "end_date": { "type": "string", "title": "End Date", "description": "ISO formatted end date of range" }, "time_series": { "items": { "$ref": "#/components/schemas/TimeSeriesPoint" }, "type": "array", "title": "Time Series" }, "breakdowns": { "$ref": "#/components/schemas/AnalyticsBreakdowns" } }, "type": "object", "required": [ "start_date", "end_date" ], "title": "AnalyticsStatsResponseSchema" }, "AvailableDomainItem": { "properties": { "domain": { "type": "string", "title": "Domain", "description": "Domain name (e.g. 'rby.one' or 'go.custom.com')" }, "is_default": { "type": "boolean", "title": "Is Default", "description": "Whether this is a platform-wide default domain" } }, "type": "object", "required": [ "domain", "is_default" ], "title": "AvailableDomainItem" }, "AvailableDomainsApiResponse": { "properties": { "domains": { "items": { "$ref": "#/components/schemas/AvailableDomainItem" }, "type": "array", "title": "Domains", "description": "List of available domains" } }, "type": "object", "required": [ "domains" ], "title": "AvailableDomainsApiResponse" }, "BatchCreateLinksApiRequest": { "properties": { "domain": { "type": "string", "minLength": 1, "title": "Domain", "description": "Target short domain for all links in this batch. Mandatory." }, "links": { "items": { "$ref": "#/components/schemas/BatchLinkItem" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Links", "description": "Array of links to generate (1 to 500)" } }, "type": "object", "required": [ "domain", "links" ], "title": "BatchCreateLinksApiRequest" }, "BatchCreateLinksApiResponse": { "properties": { "group_public_id": { "type": "string", "title": "Group Public Id" }, "total_created": { "type": "integer", "title": "Total Created" }, "links": { "items": { "$ref": "#/components/schemas/LinkApiResponse" }, "type": "array", "title": "Links" } }, "type": "object", "required": [ "group_public_id", "total_created", "links" ], "title": "BatchCreateLinksApiResponse" }, "BatchLinkItem": { "properties": { "destination_url": { "type": "string", "title": "Destination Url", "description": "Target destination URL" }, "title": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Title" }, "ios_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ios Url" }, "android_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Android Url" }, "fallback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fallback Url" }, "utm_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Source" }, "utm_medium": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Medium" }, "utm_campaign": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Campaign" }, "utm_term": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Term" }, "utm_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Content" }, "forward_parameters": { "type": "boolean", "title": "Forward Parameters", "default": true }, "og_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Title" }, "og_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Description" }, "og_image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Image" }, "geo_routing": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Geo Routing" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" } }, "type": "object", "required": [ "destination_url" ], "title": "BatchLinkItem" }, "CreateGroupApiRequest": { "properties": { "title": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Title", "description": "Name of the link group or campaign" }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Description", "description": "Optional description of the group" } }, "type": "object", "required": [ "title" ], "title": "CreateGroupApiRequest" }, "CreateLinkApiRequest": { "properties": { "destination_url": { "type": "string", "title": "Destination Url", "description": "Target destination URL to redirect to" }, "domain": { "type": "string", "minLength": 1, "title": "Domain", "description": "Target short domain (e.g. 'rby.one' or verified custom domain). Mandatory." }, "title": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Title" }, "group_public_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group Public Id", "description": "Public ID of the link group / campaign (e.g. 'grp_...')" }, "custom_alias": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Alias", "description": "Optional custom short code / slug (permitted only on verified custom domains)" }, "ios_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ios Url" }, "android_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Android Url" }, "fallback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fallback Url" }, "utm_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Source" }, "utm_medium": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Medium" }, "utm_campaign": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Campaign" }, "utm_term": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Term" }, "utm_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Content" }, "forward_parameters": { "type": "boolean", "title": "Forward Parameters", "default": true }, "og_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Title" }, "og_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Description" }, "og_image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Image" }, "geo_routing": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Geo Routing" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" } }, "type": "object", "required": [ "destination_url", "domain" ], "title": "CreateLinkApiRequest" }, "DistributionItem": { "properties": { "name": { "type": "string", "title": "Name", "description": "Category or dimension name" }, "count": { "type": "integer", "title": "Count", "description": "Number of clicks", "default": 0 }, "percentage": { "type": "number", "title": "Percentage", "description": "Percentage of total clicks", "default": 0.0 } }, "type": "object", "required": [ "name" ], "title": "DistributionItem" }, "GroupApiResponse": { "properties": { "public_id": { "type": "string", "title": "Public Id" }, "title": { "type": "string", "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "link_count": { "type": "integer", "title": "Link Count", "default": 0 }, "is_frozen": { "type": "boolean", "title": "Is Frozen", "default": false }, "status": { "$ref": "#/components/schemas/ShortLinkGroupStatus", "default": "active" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "public_id", "title" ], "title": "GroupApiResponse" }, "GroupExportApiResponse": { "properties": { "status": { "type": "string", "title": "Status", "description": "Export status: 'ready' or 'processing'" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Download Url", "description": "Time-limited signed download URL when status is ready" }, "expires_in": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expires In", "description": "Expiration time in seconds for the signed URL" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Informational message" } }, "type": "object", "required": [ "status" ], "title": "GroupExportApiResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "LinkApiResponse": { "properties": { "public_id": { "type": "string", "title": "Public Id" }, "short_code": { "type": "string", "title": "Short Code" }, "domain": { "type": "string", "title": "Domain" }, "short_url": { "type": "string", "title": "Short Url" }, "destination_url": { "type": "string", "title": "Destination Url" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "group_public_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group Public Id" }, "custom_alias": { "type": "boolean", "title": "Custom Alias", "default": false }, "is_active": { "type": "boolean", "title": "Is Active", "default": true }, "ios_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ios Url" }, "android_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Android Url" }, "fallback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fallback Url" }, "utm_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Source" }, "utm_medium": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Medium" }, "utm_campaign": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Campaign" }, "utm_term": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Term" }, "utm_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Content" }, "forward_parameters": { "type": "boolean", "title": "Forward Parameters", "default": true }, "og_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Title" }, "og_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Description" }, "og_image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Image" }, "geo_routing": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Geo Routing" }, "has_password": { "type": "boolean", "title": "Has Password", "default": false }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "public_id", "short_code", "domain", "short_url", "destination_url" ], "title": "LinkApiResponse" }, "Meta": { "properties": { "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "has_more": { "type": "boolean", "title": "Has More", "default": false }, "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Count" } }, "type": "object", "title": "Meta" }, "PaginatedList_GroupApiResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/GroupApiResponse" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "type": "object", "required": [ "data", "meta" ], "title": "PaginatedList[GroupApiResponse]" }, "PaginatedList_LinkApiResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/LinkApiResponse" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "type": "object", "required": [ "data", "meta" ], "title": "PaginatedList[LinkApiResponse]" }, "ShortLinkGroupStatus": { "type": "string", "enum": [ "processing", "active", "inactive", "deleting", "failed", "archived" ], "title": "ShortLinkGroupStatus" }, "TimeSeriesPoint": { "properties": { "date": { "type": "string", "title": "Date", "description": "Date string YYYY-MM-DD" }, "clicks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Clicks", "description": "Total human clicks on this date" }, "unique_visitors": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Unique Visitors", "description": "Unique visitors on this date" } }, "type": "object", "required": [ "date" ], "title": "TimeSeriesPoint" }, "UpdateGroupApiRequest": { "properties": { "title": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Title", "description": "Name of the link group" }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Description", "description": "Optional description of the group" } }, "type": "object", "title": "UpdateGroupApiRequest" }, "UpdateLinkApiRequest": { "properties": { "destination_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Destination Url" }, "title": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Title" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" }, "ios_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ios Url" }, "android_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Android Url" }, "fallback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fallback Url" }, "utm_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Source" }, "utm_medium": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Medium" }, "utm_campaign": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Campaign" }, "utm_term": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Term" }, "utm_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utm Content" }, "forward_parameters": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Forward Parameters" }, "og_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Title" }, "og_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Description" }, "og_image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Og Image" }, "geo_routing": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Geo Routing" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" } }, "type": "object", "title": "UpdateLinkApiRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "description": "Authentication with Bearer token formatted as `:`. For enterprise authentication, provide HMAC signature headers (`X-Rby-Key-Id`, `X-Rby-Timestamp`, `X-Rby-Signature`).", "scheme": "bearer" } } } }