{
  "openapi": "3.1.0",
  "info": {
    "title": "Shortyy Public REST API",
    "version": "1.0.0",
    "description": "Shortyy is a developer-first URL shortening and redirect management platform engineered for microsecond latency, cryptographic API key security, and seamless multi-language developer integration.\n\n### Architectural Invariants:\n1. **Link Immutability**: Once created, short links cannot be edited or updated (`PATCH` is deliberately not supported). To change a target, delete the link and create a new one.\n2. **Permanent Tombstones**: Deleted short codes are permanently archived in the reserved registry (`reserved_codes`) to ensure a deleted code can never be hijacked or recycled.\n3. **Token-Bucket Rate Limiting**: Free-tier API keys operate on continuous token-bucket replenishment (4-token burst capacity, 1 token refilled every 75 seconds).\n4. **Plan-Aware Expiration**: Free-tier API keys have an expiration ceiling of 3 hours (10,800 seconds). Paid tiers (Basic and Pro) support up to 100 years.",
    "contact": {
      "name": "Shortyy Developer Platform",
      "url": "https://shortyy.com/developers"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://api.shortyy.com/v1",
      "description": "Production API Server"
    },
    {
      "url": "http://localhost:4000/v1",
      "description": "Local Development Server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "HeaderApiKey": []
    }
  ],
  "paths": {
    "/links": {
      "post": {
        "summary": "Create Short Link",
        "description": "Generates a new shortened link with optional expiration, custom alias, click limits, and UTM tracking parameters.\n\nRequires `links:create` or `links:write` scope.",
        "operationId": "createLink",
        "security": [
          {
            "ApiKeyAuth": ["links:create", "links:write"]
          },
          {
            "HeaderApiKey": ["links:create", "links:write"]
          },
          {
            "SessionAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique client-generated key (UUID or event ID) to safely retry link creation without creating duplicates.",
            "schema": {
              "type": "string",
              "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLinkRequest"
              },
              "examples": {
                "standardLink": {
                  "summary": "Standard Short Link",
                  "value": {
                    "url": "https://stripe.com/docs/api",
                    "expires_in": "2h"
                  }
                },
                "advancedLink": {
                  "summary": "Link with Tracking and Quotas",
                  "value": {
                    "destination_url": "https://example.com/summer-campaign",
                    "custom_alias": "summer-launch",
                    "requested_expiry": "2026-12-31T23:59:59.000Z",
                    "max_clicks": 1000,
                    "utm_params": {
                      "utm_source": "newsletter",
                      "utm_medium": "email",
                      "utm_campaign": "summer_sale"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Link created successfully.",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Maximum token capacity of your rate limit bucket."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Available tokens remaining."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "string",
                  "format": "date-time"
                },
                "description": "ISO timestamp when the next token will be refilled."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateLinkResponse"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "550e8400-e29b-41d4-a716-446655440000",
                    "short_code": "summer-launch",
                    "short_url": "https://shortyy.com/summer-launch",
                    "destination_url": "https://example.com/summer-campaign",
                    "creation_channel": "sdk",
                    "status": "active",
                    "expires_at": "2026-12-31T23:59:59.000Z",
                    "max_clicks": 1000,
                    "accepted_clicks": 0,
                    "utm_params": {
                      "utm_source": "newsletter",
                      "utm_medium": "email",
                      "utm_campaign": "summer_sale"
                    },
                    "created_at": "2026-11-13T12:00:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/403Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/429RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/500InternalError"
          }
        }
      },
      "get": {
        "summary": "List Links",
        "description": "Retrieves a paginated list of shortened links belonging to the authenticated account.\n\nRequires `links:read` scope.",
        "operationId": "listLinks",
        "security": [
          {
            "ApiKeyAuth": ["links:read"]
          },
          {
            "HeaderApiKey": ["links:read"]
          },
          {
            "SessionAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number for pagination (1-indexed).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of items per page (maximum 100).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter links by lifecycle status.",
            "schema": {
              "type": "string",
              "enum": ["all", "active", "expired", "paused"],
              "default": "all"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Substring match against destination URL or short code.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of links.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListLinksResponse"
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "550e8400-e29b-41d4-a716-446655440000",
                      "short_code": "summer-launch",
                      "short_url": "https://shortyy.com/summer-launch",
                      "destination_url": "https://example.com/summer-campaign",
                      "creation_channel": "sdk",
                      "status": "active",
                      "expires_at": "2026-12-31T23:59:59.000Z",
                      "max_clicks": 1000,
                      "accepted_clicks": 42,
                      "utm_params": {},
                      "created_at": "2026-11-13T12:00:00.000Z"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "limit": 20,
                    "total": 1,
                    "totalPages": 1
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/403Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/500InternalError"
          }
        }
      }
    },
    "/links/{id}": {
      "get": {
        "summary": "Get Link Details",
        "description": "Retrieves complete metadata and status counters for a specific link by its UUID.\n\nRequires `links:read` scope.",
        "operationId": "getLink",
        "security": [
          {
            "ApiKeyAuth": ["links:read"]
          },
          {
            "HeaderApiKey": ["links:read"]
          },
          {
            "SessionAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Unique UUID identifier of the link.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Link details retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetLinkResponse"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "550e8400-e29b-41d4-a716-446655440000",
                    "short_code": "summer-launch",
                    "short_url": "https://shortyy.com/summer-launch",
                    "destination_url": "https://example.com/summer-campaign",
                    "creation_channel": "sdk",
                    "status": "active",
                    "expires_at": "2026-12-31T23:59:59.000Z",
                    "max_clicks": 1000,
                    "accepted_clicks": 42,
                    "utm_params": {},
                    "created_at": "2026-11-13T12:00:00.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/403Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/404NotFound"
          },
          "500": {
            "$ref": "#/components/responses/500InternalError"
          }
        }
      },
      "delete": {
        "summary": "Delete Link",
        "description": "Permanently archives a link, purges it from the Redis redirect cache, and reserves its short code forever in `reserved_codes` (tombstone).\n\nSubsequent requests to the short URL return HTTP 410 Gone.\nSubsequent `DELETE` calls for the same ID return HTTP 404 Not Found.\n\nRequires `links:delete` scope.",
        "operationId": "deleteLink",
        "security": [
          {
            "ApiKeyAuth": ["links:delete"]
          },
          {
            "HeaderApiKey": ["links:delete"]
          },
          {
            "SessionAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Unique UUID identifier of the link to delete.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Link permanently deleted and short code tombstoned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageResponse"
                },
                "example": {
                  "success": true,
                  "message": "Link deleted successfully"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/403Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/404NotFound"
          },
          "500": {
            "$ref": "#/components/responses/500InternalError"
          }
        }
      }
    },
    "/links/{id}/analytics": {
      "get": {
        "summary": "Get Link Analytics",
        "description": "Retrieves click analytics, remaining click quota, and last activity timestamp for a single link.\n\nRequires `analytics:read` or `links:read` scope.",
        "operationId": "getLinkAnalytics",
        "security": [
          {
            "ApiKeyAuth": ["analytics:read", "links:read"]
          },
          {
            "HeaderApiKey": ["analytics:read", "links:read"]
          },
          {
            "SessionAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Unique UUID identifier of the link.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Link click metrics retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LinkAnalyticsResponse"
                },
                "example": {
                  "success": true,
                  "data": {
                    "link_id": "550e8400-e29b-41d4-a716-446655440000",
                    "short_code": "summer-launch",
                    "destination_url": "https://example.com/summer-campaign",
                    "status": "active",
                    "accepted_clicks": 42,
                    "max_clicks": 1000,
                    "clicks_remaining": 958,
                    "last_clicked_at": "2026-11-13T12:05:00.000Z",
                    "expires_at": "2026-12-31T23:59:59.000Z",
                    "utm_params": {},
                    "created_at": "2026-11-13T12:00:00.000Z",
                    "breakdowns": {
                      "countries": {
                        "status": "coming_soon"
                      },
                      "devices": {
                        "status": "coming_soon"
                      },
                      "referrers": {
                        "status": "coming_soon"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/403Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/404NotFound"
          },
          "500": {
            "$ref": "#/components/responses/500InternalError"
          }
        }
      }
    },
    "/analytics/overview": {
      "get": {
        "summary": "Get Aggregate Overview Analytics",
        "description": "Retrieves user-wide aggregate link counts and click metrics.\n\nRequires `analytics:read` or `links:read` scope.",
        "operationId": "getAnalyticsOverview",
        "security": [
          {
            "ApiKeyAuth": ["analytics:read", "links:read"]
          },
          {
            "HeaderApiKey": ["analytics:read", "links:read"]
          },
          {
            "SessionAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "User aggregate metrics retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsOverviewResponse"
                },
                "example": {
                  "success": true,
                  "data": {
                    "metrics": {
                      "total_links": 15,
                      "active_links": 12,
                      "total_accepted_clicks": 1420
                    },
                    "top_links": [
                      {
                        "id": "550e8400-e29b-41d4-a716-446655440000",
                        "short_code": "summer-launch",
                        "accepted_clicks": 420,
                        "last_clicked_at": "2026-11-13T12:05:00.000Z",
                        "created_at": "2026-11-13T12:00:00.000Z"
                      }
                    ],
                    "breakdowns": {
                      "countries": {
                        "status": "coming_soon"
                      },
                      "devices": {
                        "status": "coming_soon"
                      },
                      "referrers": {
                        "status": "coming_soon"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/403Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/500InternalError"
          }
        }
      }
    },
    "/me": {
      "get": {
        "summary": "Get Account Profile",
        "description": "Retrieves the profile details for the authenticated user account.",
        "operationId": "getMe",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "HeaderApiKey": []
          },
          {
            "SessionAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account profile retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountProfileResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          }
        }
      }
    },
    "/me/plan": {
      "get": {
        "summary": "Get Subscription Plan & Entitlements",
        "description": "Retrieves effective subscription plan, rate limits, and feature entitlement flags.",
        "operationId": "getPlan",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "HeaderApiKey": []
          },
          {
            "SessionAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Plan capabilities and limits retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanEntitlementsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          }
        }
      }
    },
    "/me/usage": {
      "get": {
        "summary": "Get Usage & Quotas",
        "description": "Retrieves current link count, active links count, and channel rate limit window.",
        "operationId": "getUsage",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "HeaderApiKey": []
          },
          {
            "SessionAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Usage statistics retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageMetricsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sh_live_...",
        "description": "Production API key generated in the Shortyy developer dashboard.\nFormat: `Authorization: Bearer sh_live_<entropy>`"
      },
      "HeaderApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Alternative API key header.\nFormat: `X-API-Key: sh_live_<entropy>`"
      },
      "SessionAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Authenticated Supabase session JWT used by the web dashboard."
      }
    },
    "schemas": {
      "CreateLinkRequest": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Target destination URL (http:// or https://, up to 2048 characters).",
            "example": "https://stripe.com/docs/api"
          },
          "destination_url": {
            "type": "string",
            "format": "uri",
            "description": "Alias for `url`.",
            "example": "https://stripe.com/docs/api"
          },
          "expires_in": {
            "type": "string",
            "description": "Relative expiration duration (e.g. '30m', '1h', '2h', '1d'). Free tier API keys have a 3-hour limit.",
            "example": "2h"
          },
          "expiresIn": {
            "type": "string",
            "description": "CamelCase alias for `expires_in`.",
            "example": "2h"
          },
          "requested_expiry": {
            "type": "string",
            "format": "date-time",
            "description": "Absolute ISO-8601 future timestamp.",
            "example": "2026-12-31T23:59:59.000Z"
          },
          "custom_alias": {
            "type": "string",
            "minLength": 3,
            "maxLength": 64,
            "pattern": "^[a-zA-Z0-9_-]+$",
            "description": "Optional custom short code (requires Basic or Pro plan).",
            "example": "summer-launch"
          },
          "customAlias": {
            "type": "string",
            "description": "CamelCase alias for `custom_alias`."
          },
          "max_clicks": {
            "type": "integer",
            "minimum": 1,
            "description": "Maximum allowed click redirections before the link deactivates (requires Basic or Pro plan).",
            "example": 500
          },
          "maxClicks": {
            "type": "integer",
            "description": "CamelCase alias for `max_clicks`."
          },
          "utm_params": {
            "type": "object",
            "description": "Custom UTM analytics parameters (requires Basic or Pro plan for custom UTM tags).",
            "properties": {
              "utm_source": {
                "type": "string"
              },
              "utm_medium": {
                "type": "string"
              },
              "utm_campaign": {
                "type": "string"
              },
              "utm_term": {
                "type": "string"
              },
              "utm_content": {
                "type": "string"
              }
            }
          },
          "onExpiredRedirectTo": {
            "type": "string",
            "format": "uri",
            "description": "Fallback URL if visited after link expiration."
          },
          "onMaxClicksReachRedirectTo": {
            "type": "string",
            "format": "uri",
            "description": "Fallback URL if visited after click quota exhausted."
          },
          "whitelistedIPs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional IP allowlist for authorized redirects."
          },
          "blacklistedIPs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional IP blocklist."
          }
        }
      },
      "LinkModel": {
        "type": "object",
        "required": [
          "id",
          "short_code",
          "short_url",
          "destination_url",
          "status",
          "expires_at",
          "accepted_clicks",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "short_code": {
            "type": "string",
            "example": "summer-launch"
          },
          "short_url": {
            "type": "string",
            "format": "uri",
            "example": "https://shortyy.com/summer-launch"
          },
          "destination_url": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/summer-campaign"
          },
          "creation_channel": {
            "type": "string",
            "enum": ["sdk", "auth_web", "guest_web"],
            "example": "sdk"
          },
          "status": {
            "type": "string",
            "enum": ["active", "paused", "blocked", "expired"],
            "example": "active"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-12-31T23:59:59.000Z"
          },
          "max_clicks": {
            "type": "integer",
            "nullable": true,
            "example": 1000
          },
          "accepted_clicks": {
            "type": "integer",
            "example": 42
          },
          "utm_params": {
            "type": "object",
            "example": {}
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-13T12:00:00.000Z"
          }
        }
      },
      "CreateLinkResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/LinkModel"
          }
        }
      },
      "GetLinkResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/LinkModel"
          }
        }
      },
      "ListLinksResponse": {
        "type": "object",
        "required": ["success", "data", "pagination"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LinkModel"
            }
          },
          "pagination": {
            "type": "object",
            "required": ["page", "limit", "total", "totalPages"],
            "properties": {
              "page": {
                "type": "integer",
                "example": 1
              },
              "limit": {
                "type": "integer",
                "example": 20
              },
              "total": {
                "type": "integer",
                "example": 42
              },
              "totalPages": {
                "type": "integer",
                "example": 3
              }
            }
          }
        }
      },
      "LinkAnalyticsResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "link_id": {
                "type": "string",
                "format": "uuid"
              },
              "short_code": {
                "type": "string"
              },
              "destination_url": {
                "type": "string"
              },
              "status": {
                "type": "string"
              },
              "accepted_clicks": {
                "type": "integer"
              },
              "max_clicks": {
                "type": "integer",
                "nullable": true
              },
              "clicks_remaining": {
                "type": "integer",
                "nullable": true
              },
              "last_clicked_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "expires_at": {
                "type": "string",
                "format": "date-time"
              },
              "utm_params": {
                "type": "object"
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "breakdowns": {
                "type": "object"
              }
            }
          }
        }
      },
      "AnalyticsOverviewResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "metrics": {
                "type": "object",
                "properties": {
                  "total_links": {
                    "type": "integer"
                  },
                  "active_links": {
                    "type": "integer"
                  },
                  "total_accepted_clicks": {
                    "type": "integer"
                  }
                }
              },
              "top_links": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "breakdowns": {
                "type": "object"
              }
            }
          }
        }
      },
      "AccountProfileResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "user_id": {
                "type": "string"
              },
              "email": {
                "type": "string",
                "nullable": true
              },
              "display_name": {
                "type": "string",
                "nullable": true
              },
              "avatar_url": {
                "type": "string",
                "nullable": true
              },
              "status": {
                "type": "string",
                "example": "active"
              },
              "channel": {
                "type": "string",
                "example": "sdk"
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "PlanEntitlementsResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "plan_id": {
                "type": "string",
                "example": "free"
              },
              "plan_name": {
                "type": "string",
                "example": "Free Developer"
              },
              "is_paid": {
                "type": "boolean",
                "example": false
              },
              "user_status": {
                "type": "string",
                "example": "active"
              },
              "capabilities": {
                "type": "object",
                "properties": {
                  "custom_alias": {
                    "type": "boolean"
                  },
                  "list_links": {
                    "type": "boolean"
                  },
                  "max_clicks": {
                    "type": "boolean"
                  },
                  "utm_builder": {
                    "type": "boolean"
                  },
                  "qr_download": {
                    "type": "boolean"
                  }
                }
              },
              "web_max_lifetime_seconds": {
                "type": "integer",
                "example": 86400
              },
              "sdk_max_lifetime_seconds": {
                "type": "integer",
                "example": 10800
              }
            }
          }
        }
      },
      "UsageMetricsResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "links_count": {
                "type": "integer"
              },
              "active_links_count": {
                "type": "integer"
              },
              "total_accepted_clicks": {
                "type": "integer"
              },
              "rate_limit": {
                "type": "object",
                "properties": {
                  "channel": {
                    "type": "string",
                    "example": "sdk"
                  },
                  "limit": {
                    "type": "integer",
                    "example": 4
                  },
                  "window_seconds": {
                    "type": "integer",
                    "example": 75
                  }
                }
              }
            }
          }
        }
      },
      "MessageResponse": {
        "type": "object",
        "required": ["success", "message"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "message": {
            "type": "string",
            "example": "Link deleted successfully"
          }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "required": ["code", "message", "status"],
        "properties": {
          "code": {
            "type": "string",
            "description": "Machine-readable uppercase error identifier.",
            "example": "VALIDATION_FAILED"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error description.",
            "example": "Destination URL cannot be empty"
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code.",
            "example": 400
          },
          "requestId": {
            "type": "string",
            "description": "Unique tracking ID for server-side debugging.",
            "example": "req-1731498000"
          },
          "retryAfterSeconds": {
            "type": "integer",
            "description": "Only returned when code is RATE_LIMIT_EXCEEDED. Specifies seconds to back off before retrying.",
            "example": 75
          },
          "details": {
            "type": "object",
            "description": "Optional structured validation errors."
          }
        }
      },
      "StandardErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        }
      }
    },
    "responses": {
      "400ValidationError": {
        "description": "Request validation failed (invalid destination URL, bad duration format, or malformed JSON).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/StandardErrorResponse"
            },
            "example": {
              "error": {
                "code": "VALIDATION_FAILED",
                "message": "Destination URL must be a valid, public http:// or https:// address without credentials",
                "status": 400,
                "requestId": "req-400-val"
              }
            }
          }
        }
      },
      "401Unauthorized": {
        "description": "Authentication failed (missing, expired, or revoked API key).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/StandardErrorResponse"
            },
            "example": {
              "error": {
                "code": "INVALID_API_KEY",
                "message": "The provided API key is invalid or malformed",
                "status": 401,
                "requestId": "req-401-auth"
              }
            }
          }
        }
      },
      "403Forbidden": {
        "description": "Forbidden (insufficient API key scope, account suspended, or plan entitlement required).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/StandardErrorResponse"
            },
            "example": {
              "error": {
                "code": "MISSING_API_SCOPE",
                "message": "API key lacks required scope: links:delete",
                "status": 403,
                "requestId": "req-403-scope"
              }
            }
          }
        }
      },
      "404NotFound": {
        "description": "The requested link or resource was not found or does not belong to your account.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/StandardErrorResponse"
            },
            "example": {
              "error": {
                "code": "NOT_FOUND",
                "message": "Link not found",
                "status": 404,
                "requestId": "req-404-nf"
              }
            }
          }
        }
      },
      "429RateLimited": {
        "description": "Token-bucket rate limit exceeded. Client must pause for the duration of `retryAfterSeconds` before retrying.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds to wait before retrying.",
            "example": 75
          },
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            },
            "example": 4
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            },
            "example": 0
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/StandardErrorResponse"
            },
            "example": {
              "error": {
                "code": "RATE_LIMIT_EXCEEDED",
                "message": "Rate limit exceeded: You're moving a little too fast. Try again in 75 seconds.",
                "status": 429,
                "requestId": "req-429-rl",
                "retryAfterSeconds": 75
              }
            }
          }
        }
      },
      "500InternalError": {
        "description": "Internal server error (safe error payload with tracking ID).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/StandardErrorResponse"
            },
            "example": {
              "error": {
                "code": "INTERNAL_SERVER_ERROR",
                "message": "An unexpected internal error occurred. Please retry shortly.",
                "status": 500,
                "requestId": "req-500-err"
              }
            }
          }
        }
      }
    }
  }
}

