{"openapi":"3.1.0","info":{"title":"spoo.me","description":"REST API for spoo.me — free and open-source URL shortening service serving 400k+ redirects/day.\n\nAuthenticate using either:\n- **API Key**: `Authorization: Bearer spoo_<your_key>`\n- **JWT Token**: `Authorization: Bearer <jwt>` (obtained via /auth/login)\n- **Session Cookie**: `access_token` cookie (set automatically on login)","contact":{"name":"spoo.me","url":"https://spoo.me/contact","email":"support@spoo.me"},"license":{"name":"AGPL-3.0","url":"https://github.com/spoo-me/spoo/blob/main/LICENSE"},"version":"1.0.0"},"paths":{"/health":{"get":{"tags":["System"],"summary":"Health Check","description":"Check the health of the application and its dependencies.\n\nPings MongoDB and Redis to determine overall system status:\n\n- **healthy** (200): Both MongoDB and Redis are reachable.\n- **degraded** (200): MongoDB is reachable but Redis is down or not configured.\n- **unhealthy** (503): MongoDB is unreachable -- the app cannot function.\n\n**Authentication**: Not required (public endpoint)\n\n**Rate Limits**: None","operationId":"healthCheck","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Unhealthy — MongoDB is unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}},"security":[]}},"/auth/login":{"post":{"tags":["Authentication"],"summary":"Login","description":"Authenticate with email and password.\n\nReturns JWT access token and sets secure HTTP-only cookies for both\naccess and refresh tokens. The refresh token can be used at\n``POST /auth/refresh`` to obtain new tokens without re-authenticating.\n\n**Authentication**: Not required (public endpoint)\n\n**Rate Limits**: 5/min, 50/day\n\n**Security**: Returns identical error for wrong email and wrong password\nto prevent user enumeration.","operationId":"loginUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/auth/register":{"post":{"tags":["Authentication"],"summary":"Register","description":"Create a new user account with email and password.\n\nImmediately signs the user in by returning a JWT access token and setting\nsecure HTTP-only cookies. A verification email is sent best-effort; the\n``verification_sent`` field indicates whether it succeeded.\n\n**Authentication**: Not required (public endpoint)\n\n**Rate Limits**: 5/min, 50/day\n\n**Notes**: The account is created even if the verification email fails.\nThe user must verify their email before accessing protected resources.","operationId":"registerUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/auth/refresh":{"post":{"tags":["Authentication"],"summary":"Refresh Tokens","description":"Rotate the access and refresh token pair.\n\nReads the ``refresh_token`` cookie, validates it, and issues a new\naccess/refresh pair. Both cookies are replaced. If the refresh token\nis missing, expired, or invalid, all auth cookies are cleared and a\n401 response is returned.\n\n**Authentication**: Requires a valid ``refresh_token`` cookie\n\n**Rate Limits**: 20/min\n\n**Notes**: The old refresh token is invalidated after use (rotation).","operationId":"refreshTokens","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[]}},"/auth/logout":{"post":{"tags":["Authentication"],"summary":"Logout","description":"Log the current user out by clearing auth cookies.\n\nRemoves the ``access_token`` and ``refresh_token`` HTTP-only cookies.\nAlways succeeds regardless of whether the user was authenticated.\n\n**Authentication**: Not required\n\n**Rate Limits**: 60/hour","operationId":"logout","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogoutResponse"}}}}}}},"/auth/restore":{"post":{"tags":["Authentication"],"summary":"Restore Account","description":"Cancel a pending account deletion during the grace period.\n\nTwo mutually exclusive proofs: ``email`` + ``password`` validates the\naccount credentials, ``restore_token`` consumes the one-shot link from\nthe deletion notice email (the only path for OAuth-only accounts).\nEither flips the account back to ACTIVE, clears the purge deadline,\nand sends a cancellation notice to the account address. Only works\nwhile the account is PENDING_DELETION. The hard boundary is the\nerasure sweep claiming the account (typically within minutes of the\n``purge_after`` deadline from ``DELETE /api/v1/me``), so a restore in\nthe window between the deadline and the claim still succeeds; once\nerasure has started, restore is refused for good.\n\n**Authentication**: Not required (public endpoint)\n\n**Rate Limits**: 3/hour\n\n**Security**: Returns a uniform 403 for wrong credentials, unknown\nemail, invalid or spent tokens, and accounts not pending deletion —\nprevents account enumeration and state probing.","operationId":"restoreAccount","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestoreAccountRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — invalid credentials, unknown email or token, or account is not pending deletion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/auth/me":{"get":{"tags":["Authentication"],"summary":"Get Current User","description":"Return the authenticated user's full profile.\n\nIncludes email, verification status, linked OAuth providers, plan,\nand profile picture. Useful for populating the UI after login or\non page load.\n\n**Authentication**: Required (JWT or API key)\n\n**Rate Limits**: 60/min","operationId":"getCurrentUser","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Authentication"],"summary":"Update Current User","description":"Update the authenticated user's profile.\n\nCurrently only ``user_name`` is editable. Registration makes the\ndisplay name write-once, so accounts that skipped it need this to\nset one later. Send a string to set the name or ``null`` to clear it.\n\n**Authentication**: Required (JWT only — API keys cannot rename the account)\n\n**Rate Limits**: 10/min","operationId":"updateCurrentUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProfileRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/set-password":{"post":{"tags":["Authentication"],"summary":"Set Password","description":"Set a password for an OAuth-only account.\n\nAllows users who signed up via OAuth to add a password so they can\nalso log in with email + password. Fails if the user already has a\npassword set.\n\n**Authentication**: Required (JWT only — API keys cannot set passwords)\n\n**Rate Limits**: 5/min","operationId":"setPassword","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPasswordRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/send-verification":{"post":{"tags":["Authentication"],"summary":"Send Verification Email","description":"Send a 6-digit OTP verification code to the user's email.\n\nThe code expires after the duration returned in ``expires_in`` (seconds).\nReturns 400 if the user's email is already verified.\n\n**Authentication**: Required (JWT or API key)\n\n**Rate Limits**: 1/minute, 3/hour\n\n**Notes**: Previous unused OTPs are invalidated when a new one is sent.","operationId":"sendVerification","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendVerificationResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/auth/verify-email":{"post":{"tags":["Authentication"],"summary":"Verify Email","description":"Verify the user's email address using a 6-digit OTP code.\n\nOn success, new JWT tokens are issued with ``email_verified=true`` in the\nclaims, and auth cookies are updated. A welcome email is sent best-effort.\n\n**Authentication**: Required (JWT or API key)\n\n**Rate Limits**: 10/hour\n\n**Notes**: The OTP must match the most recently sent code and must not\nbe expired. Expired or already-used codes are rejected.","operationId":"verifyEmail","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyEmailRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyEmailResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/request-password-reset":{"post":{"tags":["Authentication"],"summary":"Request Password Reset","description":"Request a password-reset OTP to be sent via email.\n\nAlways returns the same success response regardless of whether the\nemail is registered. This prevents user enumeration attacks.\n\n**Authentication**: Not required (public endpoint)\n\n**Rate Limits**: 3/hour\n\n**Security**: Timing-safe -- response time is constant whether or not\nthe account exists.","operationId":"requestPasswordReset","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestPasswordResetRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/auth/reset-password":{"post":{"tags":["Authentication"],"summary":"Reset Password","description":"Reset the account password using a 6-digit OTP code.\n\nThe OTP must have been requested via ``POST /auth/request-password-reset``.\nOn success the password is updated immediately and the OTP is consumed.\n\n**Authentication**: Not required (public endpoint)\n\n**Rate Limits**: 5/hour\n\n**Notes**: Expired or already-used OTPs are rejected with a 400 error.","operationId":"resetPassword","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/auth/device/token":{"post":{"tags":["Authentication"],"summary":"Exchange Device Auth Code","description":"Exchange a one-time device auth code for JWT tokens.\n\nThe code is obtained from the callback page after the user authenticates\non spoo.me. The PKCE ``code_verifier`` must match the ``code_challenge``\nthe app sent when initiating the flow. Returns access and refresh tokens\nscoped to the app's grant.\n\n**Authentication**: Not required (public endpoint)\n\n**Rate Limits**: 10/min","operationId":"exchangeDeviceCode","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceTokenRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceTokenResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/auth/device/refresh":{"post":{"tags":["Authentication"],"summary":"Refresh Device Auth Tokens","description":"Refresh an app's JWT tokens using a refresh token.\n\nAccepts the refresh token in the request body (not cookies) for use\nby external apps (browser extensions, desktop, CLI, bots).  If the\nrefresh token contains an ``app_id`` claim, the server verifies the\napp grant is still active — revoked apps cannot refresh — and re-reads\nthe grant's scopes so scope changes propagate on the next refresh.\n\n**Authentication**: Not required (the refresh token itself is the credential)\n\n**Rate Limits**: 20/min","operationId":"refreshDeviceTokens","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceRefreshRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceRefreshResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/auth/onboarding":{"get":{"tags":["Authentication"],"summary":"Get Onboarding State","description":"Return the caller's onboarding resume pointer.\n\n**Authentication**: Required (JWT or API key)\n\n**Rate Limits**: 60/min\n\n**Notes**: The pointer self-expires 24h after the last write. Empty\n(`step: null`) means nothing to resume — never started, expired, or\ncompleted. Whether the account has *finished* onboarding is\n`user.onboarded_at` on `/auth/me`, not part of this cache.","operationId":"getOnboardingState","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingStateResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Authentication"],"summary":"Update Onboarding State","description":"Persist the caller's resume pointer (refreshes the 24h TTL).\n\n**Authentication**: Required (JWT or API key)\n\n**Rate Limits**: 30/min\n\n**Notes**: Best-effort — if Redis is unavailable the response echoes\nthe submitted state without persisting it; clients keep their local\ncopy as the fallback source of truth.","operationId":"putOnboardingState","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingStateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingStateResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/onboarding/complete":{"post":{"tags":["Authentication"],"summary":"Complete Onboarding","description":"Mark onboarding finished for this account.\n\nStamps `onboarded_at` on the user document (first completion wins —\nrepeat calls are idempotent and keep the original timestamp), records\nthe optional HDYHAU answer, and drops the resume pointer.\n\n**Authentication**: Required (JWT or API key)\n\n**Rate Limits**: 30/min","operationId":"completeOnboarding","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingCompleteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingCompleteResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/oauth/providers":{"get":{"tags":["OAuth"],"summary":"List OAuth Providers","description":"List all OAuth providers linked to the authenticated user's account.\n\nReturns each linked provider's name, email, and link date, plus whether\nthe user has a password set (needed by the UI to decide if unlinking\nthe last provider is allowed).\n\n**Authentication**: Required (JWT or API key)\n\n**Rate Limits**: 60/min","operationId":"listOAuthProviders","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProvidersResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/oauth/providers/{provider_name}/unlink":{"delete":{"tags":["OAuth"],"summary":"Unlink OAuth Provider","description":"Remove an OAuth provider link from the authenticated user's account.\n\nFails if the provider is the user's only authentication method (i.e.,\nno password set and no other providers linked).\n\n**Authentication**: Required (JWT or API key)\n\n**Rate Limits**: 5/min","operationId":"unlinkOAuthProvider","parameters":[{"name":"provider_name","in":"path","required":true,"schema":{"type":"string","title":"Provider Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/oauth/{provider}":{"get":{"tags":["OAuth"],"summary":"OAuth Login","description":"Initiate the OAuth authorization flow for the given provider.\n\nRedirects the user to the provider's consent screen (e.g., Google,\nGitHub). After the user grants access, the provider redirects back\nto ``GET /oauth/{provider}/callback``.\n\n**Authentication**: Not required (public endpoint)\n\n**Rate Limits**: 10/min\n\n**Supported providers**: google, github (configurable)","operationId":"initiateOAuthLogin","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","title":"Provider"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/oauth/{provider}/callback":{"get":{"tags":["OAuth"],"summary":"OAuth Callback","description":"Handle the OAuth provider callback after user authorization.\n\nValidates the CSRF state parameter, exchanges the authorization code for\nan access token, fetches the user's profile from the provider, and then\neither logs in an existing user or creates a new account. On success,\nredirects to ``/dashboard`` with JWT cookies set.\n\n**Authentication**: Not required (public endpoint)\n\n**Rate Limits**: 20/min\n\n**Notes**: This endpoint is called by the OAuth provider, not directly\nby the client. The ``state`` query parameter is required for CSRF protection.","operationId":"oauthCallback","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","title":"Provider"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/oauth/{provider}/link":{"get":{"tags":["OAuth"],"summary":"Link OAuth Provider","description":"Initiate an OAuth flow to link a provider to the authenticated account.\n\nSimilar to ``GET /oauth/{provider}`` but includes the user's ID in the\nstate token so the callback knows to link rather than log in. The user\nmust already be authenticated.\n\n**Authentication**: Required (JWT or API key)\n\n**Rate Limits**: 5/min","operationId":"linkOAuthProvider","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","title":"Provider"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/shorten":{"post":{"tags":["URL Shortening"],"summary":"Create Shortened URL","description":"Create a new shortened URL.\n\nCreate a shortened URL with optional customization including password\nprotection, expiration, click limits, and bot blocking. Authenticated\nusers may target an owned, ACTIVE custom domain via the ``domain`` field.\n\n**Emoji aliases**: ``alias`` also accepts an emoji-only short code\n(e.g. ``🚀🔥``) — 1-15 fully-qualified emoji; ZWJ sequences, flags,\nkeycaps, and text-style symbols are rejected (they render or copy\ninconsistently across platforms). Set ``alias_type: \"emoji\"`` to\nauto-generate an emoji code instead of an alphanumeric one. Stored\nand returned in canonical form (variation selectors stripped).\n\n**Authentication**: Optional — higher rate limits when authenticated.\nRequired if ``domain`` is supplied.\n\n**API Key Scope**: `shorten:create` or `admin:all`\n\n**Rate Limits**:\n\n- Authenticated: 60/min, 5,000/day\n- Anonymous: 20/min, 1,000/day\n\n**Anonymous Usage Consequences**:\n\n- Lower rate limits\n- Cannot manage or view URLs later\n- Cannot use private stats\n- URLs not linked to any account\n- Cannot use custom domains\n- Cannot use geo targeting\n- Cannot use A/B variants\n- Cannot set an expired-link fallback\n- Cannot use custom meta tags","operationId":"shortenUrl","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUrlRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UrlResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{},{"ApiKeyAuth":[]},{"JWTAuth":[]}]}},"/api/v1/shorten/check-alias":{"get":{"tags":["URL Shortening"],"summary":"Check Alias Availability","description":"Check whether a proposed alias would be accepted by POST /api/v1/shorten.\n\nReason codes on a negative result (``length``/``format``/``reserved``/\n``taken``/``emoji_policy``) let the UI render precise inline feedback\nwithout duplicating the validation rules. Emoji aliases are checked in\ncanonical form (variation selectors stripped).\n\nPass ``domain`` to scope the check to a custom-domain tenant — required\nfor the create modal's live availability indicator when the user has\npicked a non-default domain. Authz mirrors the shorten endpoint: anon\ncallers can't probe custom domains; authed callers must own the target.\n\n**Authentication**: Optional — higher rate limits when authenticated.\nRequired if ``domain`` is supplied.","operationId":"checkAliasAvailability","parameters":[{"name":"alias","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Candidate alias to check (alphanumeric or emoji-only).","examples":["mylink","🚀🔥"],"title":"Alias"},"description":"Candidate alias to check (alphanumeric or emoji-only)."},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"description":"Scope the availability check to a custom domain fqdn. Requires authentication + ownership of an ACTIVE custom domain. Omit for the system default namespace.","examples":["links.acme.com"],"title":"Domain"},"description":"Scope the availability check to a custom domain fqdn. Requires authentication + ownership of an ACTIVE custom domain. Omit for the system default namespace."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AliasCheckResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{},{"ApiKeyAuth":[]},{"JWTAuth":[]}]}},"/api/v1/emoji-set":{"get":{"tags":["URL Shortening"],"summary":"Accepted Emoji Set","description":"Return the accepted emoji catalogue and its policy caps.\n\n``emoji`` lists every single-codepoint emoji a custom alias may use\n(the picker's list), ordered by canonical Unicode group and within-group\norder so a picker opens on Smileys rather than symbols. Each entry\ncarries ``c`` (the raw canonical character), ``n`` (a searchable name like\n\"rocket\"), ``g`` (its canonical Unicode category, e.g. \"Smileys &\nEmotion\", for category tabs), ``gen`` (whether it is in the server's\nauto-generation pool), and an optional ``k`` (extra search aliases when\nthe source lists any). Skin tone is a client-side modifier appended to a\nbase emoji, so skin-tone variants are not enumerated.\n\n**Authentication**: None. The response is identical for everyone.\n\n**Caching**: Fresh for a day, then served stale for a week while\nrevalidating. A content-derived ``ETag`` is returned; send it back as\n``If-None-Match`` to get a ``304`` when the set is unchanged.\n\n**Rate Limits**: 60/min, 2,000/day.","operationId":"getEmojiSet","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmojiSetResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[]}},"/api/v1/urls":{"get":{"tags":["Link Management"],"summary":"List Your URLs","description":"List all URLs owned by the authenticated user.\n\nReturns a paginated list of shortened URLs with support for filtering,\nsorting, and full-text search on aliases and destination URLs.\n\n**Authentication**: Required.\n\n**API Key Scope**: `urls:manage`, `urls:read`, or `admin:all`\n\n**Rate Limits**: 60/min, 5,000/day\n\n**Pagination**: Use `page` and `pageSize` query params. Response includes\n`hasNext` boolean and `total` count.\n\n**Sorting**: Sort by `created_at`, `last_click`, or `total_clicks` in\nascending or descending order.\n\n**Filtering**: Pass a JSON-encoded `filter` parameter with fields like\n`status`, `createdAfter`, `createdBefore`, `passwordSet`, `maxClicksSet`,\n`search`, `tagIds`, `tagNames` and `tagsMatch`.","operationId":"listUrls","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (default: 1)","examples":[1],"default":1,"title":"Page"},"description":"Page number (default: 1)"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (default: 20, max: 100)","examples":[20],"default":20,"title":"Pagesize"},"description":"Items per page (default: 20, max: 100)"},{"name":"sortBy","in":"query","required":false,"schema":{"enum":["created_at","last_click","total_clicks"],"type":"string","description":"Field to sort by","default":"created_at","title":"Sortby"},"description":"Field to sort by"},{"name":"sortOrder","in":"query","required":false,"schema":{"enum":["ascending","asc","1","descending","desc","-1"],"type":"string","description":"Sort direction","default":"descending","title":"Sortorder"},"description":"Sort direction"},{"name":"filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"description":"JSON string containing filter criteria for URLs. Format: `{\"field\": value}`\n\n**Available filter fields:**\n\n- **status** — Filter by URL status (`\"ACTIVE\"` or `\"INACTIVE\"`)\n- **createdAfter** — Filter URLs created after this date (ISO 8601 datetime or Unix timestamp)\n- **createdBefore** — Filter URLs created before this date (ISO 8601 datetime or Unix timestamp)\n- **passwordSet** — Filter by password protection (boolean: `true`/`false`)\n- **maxClicksSet** — Filter by click limit presence (boolean: `true`/`false`)\n- **search** — Search in alias or long_url (case-insensitive string)\n- **tagIds** — Only links carrying these tags, by id (array of strings)\n- **tagNames** — Same, by tag name; unknown names match nothing\n- **tagsMatch** — `\"any\"` (default) or `\"all\"`; how multiple tags combine\n\n**Value formats:**\n\n- **status**: String — `\"ACTIVE\"` or `\"INACTIVE\"` (case-sensitive)\n- **createdAfter / createdBefore**: ISO 8601 datetime string (e.g., `\"2024-01-01T00:00:00Z\"`) or Unix timestamp (e.g., `1704067200`)\n- **passwordSet / maxClicksSet**: Boolean — `true` or `false`\n- **search**: String — case-insensitive search term\n- **tagIds / tagNames**: Array of strings\n- **tagsMatch**: String — `\"any\"` or `\"all\"`\n\n**Examples:**\n\n- `{\"status\": \"ACTIVE\"}` — Only active URLs\n- `{\"passwordSet\": true}` — Only password-protected URLs\n- `{\"createdAfter\": \"2024-01-01T00:00:00Z\"}` — URLs created after Jan 1, 2024\n- `{\"status\": \"ACTIVE\", \"maxClicksSet\": true}` — Active URLs with click limits\n- `{\"search\": \"example\"}` — URLs containing \"example\" in alias or long_url\n- `{\"tagNames\": [\"launch\", \"q3\"], \"tagsMatch\": \"all\"}` — URLs tagged both launch and q3\n- `{\"createdAfter\": \"2024-01-01\", \"createdBefore\": \"2024-12-31\", \"status\": \"ACTIVE\"}` — Active URLs from 2024","examples":["{\"status\":\"ACTIVE\"}","{\"passwordSet\": true}","{\"createdAfter\": \"2024-01-01T00:00:00Z\"}","{\"status\": \"ACTIVE\", \"maxClicksSet\": true}","{\"search\": \"example\"}","{\"createdAfter\": \"2024-01-01\", \"createdBefore\": \"2024-12-31\", \"status\": \"ACTIVE\"}"],"title":"Filter"},"description":"JSON string containing filter criteria for URLs. Format: `{\"field\": value}`\n\n**Available filter fields:**\n\n- **status** — Filter by URL status (`\"ACTIVE\"` or `\"INACTIVE\"`)\n- **createdAfter** — Filter URLs created after this date (ISO 8601 datetime or Unix timestamp)\n- **createdBefore** — Filter URLs created before this date (ISO 8601 datetime or Unix timestamp)\n- **passwordSet** — Filter by password protection (boolean: `true`/`false`)\n- **maxClicksSet** — Filter by click limit presence (boolean: `true`/`false`)\n- **search** — Search in alias or long_url (case-insensitive string)\n- **tagIds** — Only links carrying these tags, by id (array of strings)\n- **tagNames** — Same, by tag name; unknown names match nothing\n- **tagsMatch** — `\"any\"` (default) or `\"all\"`; how multiple tags combine\n\n**Value formats:**\n\n- **status**: String — `\"ACTIVE\"` or `\"INACTIVE\"` (case-sensitive)\n- **createdAfter / createdBefore**: ISO 8601 datetime string (e.g., `\"2024-01-01T00:00:00Z\"`) or Unix timestamp (e.g., `1704067200`)\n- **passwordSet / maxClicksSet**: Boolean — `true` or `false`\n- **search**: String — case-insensitive search term\n- **tagIds / tagNames**: Array of strings\n- **tagsMatch**: String — `\"any\"` or `\"all\"`\n\n**Examples:**\n\n- `{\"status\": \"ACTIVE\"}` — Only active URLs\n- `{\"passwordSet\": true}` — Only password-protected URLs\n- `{\"createdAfter\": \"2024-01-01T00:00:00Z\"}` — URLs created after Jan 1, 2024\n- `{\"status\": \"ACTIVE\", \"maxClicksSet\": true}` — Active URLs with click limits\n- `{\"search\": \"example\"}` — URLs containing \"example\" in alias or long_url\n- `{\"tagNames\": [\"launch\", \"q3\"], \"tagsMatch\": \"all\"}` — URLs tagged both launch and q3\n- `{\"createdAfter\": \"2024-01-01\", \"createdBefore\": \"2024-12-31\", \"status\": \"ACTIVE\"}` — Active URLs from 2024"},{"name":"filterBy","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"description":"Alias for filter parameter.","title":"Filterby"},"description":"Alias for filter parameter."},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"description":"Filter URLs by exact custom domain fqdn.","examples":["links.acme.com"],"title":"Domain"},"description":"Filter URLs by exact custom domain fqdn."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UrlListResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Link Management"],"summary":"Bulk Delete URLs on a Custom Domain","description":"Bulk-delete all URLs the caller owns on the given custom domain.\n\n**Authentication**: Required.\n\n**API Key Scope**: `urls:manage` or `admin:all`\n\n**Rate Limits**: 5/min, 50/day.\n\n**Restrictions**: refuses the system-default domain — protects against\naccidental nuke of the user's entire spoo.me URL inventory. Caller must\nown the domain.","operationId":"bulkDeleteUrls","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":253,"description":"Custom domain fqdn whose URLs should be deleted.","examples":["links.acme.com"],"title":"Domain"},"description":"Custom domain fqdn whose URLs should be deleted."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteUrlsResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/urls/{url_id}":{"get":{"tags":["Link Management"],"summary":"Get URL by ID","description":"Fetch a single URL you own by its id.\n\nReturns the same item shape as one element of `GET /urls` — including\nderived `status`, so expired/disabled/blocked links return normally\nwith their status field (you are reading your inventory, not following\na redirect).\n\n**Authentication**: Required — you must own the URL.\n\n**API Key Scope**: `urls:manage`, `urls:read`, or `admin:all`\n\n**Rate Limits**: 60/min, 5,000/day\n\n**Errors**:\n\n- `400` — malformed id (not a valid ObjectId)\n- `404` — no URL with that id in your account. A URL owned by someone\n  else answers identically; this endpoint never confirms foreign ids.","operationId":"getUrl","parameters":[{"name":"url_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the URL (MongoDB ObjectId).","title":"Url Id"},"description":"Unique identifier of the URL (MongoDB ObjectId)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UrlListItem"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Link Management"],"summary":"Update URL","description":"Update an existing URL's properties.\n\nPartially update a shortened URL. Only provided fields are modified; omitted\nfields remain unchanged. Pass `null` to remove optional settings like\n`password`, `max_clicks`, or `expire_after`.\n\n**Authentication**: Required — you must own the URL.\n\n**API Key Scope**: `urls:manage` or `admin:all`\n\n**Rate Limits**: 120/min, 2,000/day\n\n**Updatable Fields**: `long_url`, `alias`, `password`, `block_bots`,\n`max_clicks`, `expire_after`, `private_stats`, `status`, `domain`,\n`geo_rules`, `ab_variants`, `expired_redirect_url`, `meta_tags`\n\n**Notes**:\n\n- Setting `max_clicks` to `0` or `null` removes the click limit\n- Changing the `alias` checks availability and may fail with 409 Conflict\n- Setting `domain` moves the URL to a different tenant; caller must own\n  the target as an ACTIVE custom domain, or pass `null` to move back to\n  the system default. Alias collision is verified on the target.\n- `geo_rules` replaces the whole map; pass `null` or `{}` to remove all\n  rules\n- `ab_variants` replaces the whole list; pass `null` or `[]` to remove all\n  variants\n- `expired_redirect_url` is where visitors land once the link has expired;\n  pass `null` to go back to the expired page\n- The `url_id` is the MongoDB ObjectId, not the alias","operationId":"updateUrl","parameters":[{"name":"url_id","in":"path","required":true,"schema":{"type":"string","minLength":24,"maxLength":24,"pattern":"^[0-9a-f]{24}$","description":"Unique identifier of the URL","title":"Url Id"},"description":"Unique identifier of the URL"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUrlRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUrlResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Link Management"],"summary":"Delete URL","description":"Delete a URL permanently.\n\n**This action is IRREVERSIBLE.** The URL and its alias are permanently\ndeleted, and the alias may be reclaimed by another user afterward.\nHistorical click analytics are not removed; they are erased when the\nowning account is deleted.\n\n**Authentication**: Required — you must own the URL.\n\n**API Key Scope**: `urls:manage` or `admin:all`\n\n**Rate Limits**: 60/min, 1,000/day\n\n**Recommendation**: Consider setting the URL status to `INACTIVE` via\n`PATCH /urls/{url_id}/status` instead if you may want to restore it later.","operationId":"deleteUrl","parameters":[{"name":"url_id","in":"path","required":true,"schema":{"type":"string","minLength":24,"maxLength":24,"pattern":"^[0-9a-f]{24}$","description":"Unique identifier of the URL","title":"Url Id"},"description":"Unique identifier of the URL"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteUrlResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/urls/{domain}/{alias}":{"get":{"tags":["Link Management"],"summary":"Get URL by Domain and Alias","description":"Fetch a single URL you own by its natural key: domain + alias.\n\nThe address every short link is already known by — no id lookup\nround-trip needed. Returns the same item shape as one element of\n`GET /urls`, status-blind for the owner (expired/disabled/blocked\nlinks return with their status field).\n\n**Authentication**: Required — you must own the URL.\n\n**API Key Scope**: `urls:manage`, `urls:read`, or `admin:all`\n\n**Rate Limits**: 60/min, 5,000/day\n\n**Errors**:\n\n- `404` — no URL at that address in your account. Unknown domains and\n  links owned by someone else answer identically; this endpoint never\n  confirms what exists outside your account.\n\n**Note**: only current-generation links resolve here — that is all the\nmanaged collection holds.","operationId":"getUrlByAddress","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","maxLength":253,"description":"Domain the short link lives on. Always explicit: pass the system domain (e.g. `spoo.me`) for default-namespace links or an owned custom domain fqdn. Case and `:port` are ignored.","examples":["spoo.me","links.acme.com"],"title":"Domain"},"description":"Domain the short link lives on. Always explicit: pass the system domain (e.g. `spoo.me`) for default-namespace links or an owned custom domain fqdn. Case and `:port` are ignored."},{"name":"alias","in":"path","required":true,"schema":{"type":"string","description":"Short code of the URL. Emoji aliases arrive percent-encoded.","examples":["mylink"],"title":"Alias"},"description":"Short code of the URL. Emoji aliases arrive percent-encoded."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UrlListItem"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/urls/bulk/delete":{"post":{"tags":["Link Management"],"summary":"Bulk Delete URLs","description":"Permanently delete up to 100 URLs you own, addressed by id.\n\n**This action is irreversible.** Deleted aliases become available\nfor anyone to claim. Historical analytics are not removed.\n\nNot to be confused with `DELETE /api/v1/urls?domain=` (bulk delete\nby custom domain): that operation answers \"everything on this\ndomain\", this one answers \"exactly these links\".\n\n**Per-item verdicts** (`error_code`): `not_found` — no such URL in\nyour account (an id you don't own answers the same); `forbidden` —\nthe URL is admin-blocked and cannot be deleted.\n\n**Retry semantics**: re-sending the batch after a timeout is safe;\nalready-deleted ids report `not_found`, which a client should treat\nas success-equivalent for delete.\n\n**Rate Limits**: 30/min, 100/day — counted per request, not per id.","operationId":"bulkDeleteUrlsByIds","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteUrlsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUrlOperationResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/urls/bulk/status":{"post":{"tags":["Link Management"],"summary":"Bulk Update URL Status","description":"Activate or deactivate up to 100 URLs you own in one request.\n\nSemantics match the single-item status endpoint exactly: `ACTIVE`\nenables redirects, `INACTIVE` disables them, `EXPIRED` URLs set to\n`ACTIVE` reactivate, and setting the status a link already has is a\nsuccess no-op.\n\n**Per-item verdicts** (`error_code`): `not_found` — no such URL in\nyour account; `forbidden` — the URL is admin-blocked and cannot be\nmodified.\n\n**Rate Limits**: 60/min, 200/day — counted per request, not per id.","operationId":"bulkUpdateUrlStatus","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpdateStatusRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUrlOperationResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/urls/bulk/expiry":{"post":{"tags":["Link Management"],"summary":"Bulk Update URL Expiry","description":"Set or clear the expiration on up to 100 URLs you own.\n\nOne value for the whole batch — ISO 8601 or epoch seconds, must be\nin the future (a past value rejects the whole request; it could\nnever be right for any item). `null` clears expiry. `EXPIRED` URLs\nwhose expiry is extended or cleared reactivate, exactly like the\nsingle-item update.\n\n**Per-item verdicts** (`error_code`): `not_found` — no such URL in\nyour account; `forbidden` — the URL is admin-blocked and cannot be\nmodified.\n\n**Rate Limits**: 60/min, 200/day — counted per request, not per id.","operationId":"bulkUpdateUrlExpiry","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpdateExpiryRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUrlOperationResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/urls/bulk/domain":{"post":{"tags":["Link Management"],"summary":"Bulk Move URL Domain","description":"Move up to 100 URLs you own to a different domain in one request.\n\nOne target for the whole batch: a custom domain you own (it must be\nverified and ACTIVE — an unusable target rejects the whole request,\nsince it could never be right for any item), or `null` to move back\nto the system default.\n\nSemantics match the single-item domain update exactly, per item:\nalready on the target is a success no-op, a reserved alias cannot\nmove onto the system default, and the alias must be free on the\ntarget namespace. Within one batch, items are processed in request\norder — two links with the same alias moving to one target means the\nfirst wins and the second reports `conflict`, deterministically.\n\n**Per-item verdicts** (`error_code`): `not_found` — no such URL in\nyour account; `forbidden` — the URL is admin-blocked; `conflict` —\nalias already taken on the target; `validation_error` — reserved\nalias on the system default.\n\n**Retry semantics**: re-sending the batch is safe — items that\nalready moved report success no-ops.\n\n**Rate Limits**: 60/min, 200/day — counted per request, not per id.","operationId":"bulkUpdateUrlDomain","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkMoveDomainRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUrlOperationResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/urls/bulk/tags":{"post":{"tags":["Link Management"],"summary":"Bulk Tag URLs","description":"Add and remove tags (by tag id) on up to 100 URLs you own in one request.\n\nPer item the result is the link's current tags minus `remove`, plus\n`add` (kept once, order preserved). A link that already reads that\nway is a success no-op. Every id in `add` must be one of your tags\n(`GET /tags`); an unknown one rejects the whole request before any\nitem is touched.\n\n**Per-item verdicts** (`error_code`): `not_found` — no such URL in\nyour account; `forbidden` — the URL is admin-blocked;\n`validation_error` — the result would exceed 10 tags on that link.\n\n**Retry semantics**: re-sending the batch is safe — items already\ncarrying the result report success no-ops.\n\n**Rate Limits**: 60/min, 200/day — counted per request, not per id.","operationId":"bulkTagUrls","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkTagUrlsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUrlOperationResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/tags":{"get":{"tags":["Tags"],"summary":"List Your Tags","description":"Every tag in your account with the number of links carrying it,\noldest first.\n\n**API Key Scope**: `urls:manage`, `urls:read`, or `admin:all`\n\n**Rate Limits**: 60/min, 5,000/day","operationId":"listTags","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagListResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Tags"],"summary":"Create a Tag","description":"Create a tag. Names are lowercased and trimmed; a name you already\nhave answers `409 conflict`. Omit `color` to get the least-used palette\ncolour in your account; omit `icon` for the generic tag glyph. At most\n500 tags per account.\n\n**API Key Scope**: `urls:manage` or `admin:all`\n\n**Rate Limits**: 30/min","operationId":"createTag","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTagRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/tags/{tag_id}":{"patch":{"tags":["Tags"],"summary":"Rename or Recolour a Tag","description":"Change the name, colour or icon. Links keep pointing at the tag\nby id, so a rename shows up everywhere at once. Renaming onto a name you\nalready have answers `409 conflict`.\n\n**API Key Scope**: `urls:manage` or `admin:all`\n\n**Rate Limits**: 30/min","operationId":"updateTag","parameters":[{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","description":"Tag id (MongoDB ObjectId), as returned by GET /tags.","examples":["665f0c2f9e7a4b1d2c3d4e5f"],"title":"Tag Id"},"description":"Tag id (MongoDB ObjectId), as returned by GET /tags."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTagRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Tags"],"summary":"Delete a Tag","description":"Delete the tag and remove it from every link that carried it. The\nlinks themselves are untouched otherwise.\n\n**API Key Scope**: `urls:manage` or `admin:all`\n\n**Rate Limits**: 10/min. Deleting fans out an update over every link\nyou own, so it carries the same budget as bulk delete.","operationId":"deleteTag","parameters":[{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","description":"Tag id (MongoDB ObjectId), as returned by GET /tags.","examples":["665f0c2f9e7a4b1d2c3d4e5f"],"title":"Tag Id"},"description":"Tag id (MongoDB ObjectId), as returned by GET /tags."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagDeleteResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/urls/claim":{"post":{"tags":["Link Management"],"summary":"Claim anonymous URLs","description":"Claim anonymously-created URLs into your account.\n\nEach item pairs a URL id with the one-time `claim_token` returned by\nthe anonymous shorten call — the bearer proof of creation. Items\nresolve independently and the batch never hard-fails: `claimed`\n(ownership transferred, token burned), `already_yours` (idempotent\nrepeat), or `invalid` (unknown id, wrong token, or a link that is not\nclaimable — deliberately indistinguishable).\n\nThe claim_token is single-use and is invalidated immediately on\nsuccess. Claimed links join the account like any owned link:\ndashboard, management, and full stats history included.\n\n**Authentication**: Required.\n\n**API Key Scope**: `urls:manage` or `admin:all`\n\n**Rate Limits**: 30/min, 500/day","operationId":"claimUrls","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimUrlsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimUrlsResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/urls/{url_id}/status":{"patch":{"tags":["Link Management"],"summary":"Update URL Status","description":"Update only the status of a URL (ACTIVE / INACTIVE).\n\nToggle a URL between active and inactive without modifying other properties.\n\n**Authentication**: Required — you must own the URL.\n\n**API Key Scope**: `urls:manage` or `admin:all`\n\n**Rate Limits**: 120/min, 2,000/day\n\n**Status Values** (user-editable via this endpoint):\n\n- `ACTIVE` — URL is accessible and redirects normally\n- `INACTIVE` — URL is disabled and returns an error page\n\n**Note**: `BLOCKED` is an admin-set status — blocked URLs cannot be modified\nor deleted by the owner. `EXPIRED` URLs (auto-set on max clicks or expiry\ntime) can be reactivated by setting status back to `ACTIVE` — but only\nafter the expiry condition is lifted (raise/clear `max_clicks`, extend/\nclear `expire_after` via PATCH), otherwise the URL immediately reads\nas expired again.\n\n**Use Cases**:\n\n- Set `INACTIVE` to temporarily disable redirects without deleting the URL\n- Set `ACTIVE` to re-enable a previously disabled URL","operationId":"updateUrlStatus","parameters":[{"name":"url_id","in":"path","required":true,"schema":{"type":"string","minLength":24,"maxLength":24,"pattern":"^[0-9a-f]{24}$","description":"Unique identifier of the URL","title":"Url Id"},"description":"Unique identifier of the URL"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUrlStatusRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUrlResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats":{"get":{"tags":["Statistics"],"summary":"URL Statistics","description":"Get aggregated click statistics across all URLs you own.\n\nRetrieve click analytics with flexible grouping, filtering, and\ntime-range options.\n\n**Authentication**: Required.\n\n**API Key Scope**: `stats:read`, `urls:read`, or `admin:all`\n\n**Rate Limits**: 60/min, 5,000/day\n\n**Grouping Dimensions**: `time`, `browser`, `os`, `device`, `country`,\n`city`, `referrer`, `short_code`, `utm_source`, `utm_medium`,\n`utm_campaign`, `variant`\n\n**Metrics**: `clicks`, `unique_clicks`\n\n**Filtering**: Filter by `browser`, `os`, `device`, `country`, `city`,\n`referrer`, `short_code`, `url_id`, `variant`, or the `utm_*` tags using\nquery params or a JSON `filters` object. Filters slice your own aggregate —\n`url_id` values you do not own simply match nothing. For statistics on\na single link, prefer `GET /stats/links/{url_id}`.","operationId":"getStats","parameters":[{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Start of time range. Accepts ISO 8601 datetime string (e.g., `2025-01-01T00:00:00Z`) or Unix timestamp in seconds (e.g., `1735689600`). If omitted, defaults to 7 days before `end_date`.","examples":["2025-01-01T00:00:00Z"],"title":"Start Date"},"description":"Start of time range. Accepts ISO 8601 datetime string (e.g., `2025-01-01T00:00:00Z`) or Unix timestamp in seconds (e.g., `1735689600`). If omitted, defaults to 7 days before `end_date`."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"End of time range. Accepts ISO 8601 datetime string (e.g., `2025-12-31T23:59:59Z`) or Unix timestamp in seconds (e.g., `1767225599`). If omitted, defaults to now.","examples":["2025-12-31T23:59:59Z"],"title":"End Date"},"description":"End of time range. Accepts ISO 8601 datetime string (e.g., `2025-12-31T23:59:59Z`) or Unix timestamp in seconds (e.g., `1767225599`). If omitted, defaults to now."},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Comma-separated grouping dimensions for the statistics breakdown. Defaults to `time` if omitted.\n\n**Available dimensions:**\n\n- `time` — group by time buckets (day/week/month, auto-selected based on range)\n- `browser` — group by browser name (e.g., Chrome, Firefox, Safari)\n- `os` — group by operating system (e.g., Windows, macOS, Linux)\n- `device` — group by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — group by country\n- `city` — group by city\n- `referrer` — group by referrer URL\n- `short_code` — group by URL alias\n- `utm_source` — group by the `utm_source` tag on the short link (untagged clicks appear as `(none)`)\n- `utm_medium` — group by the `utm_medium` tag\n- `utm_campaign` — group by the `utm_campaign` tag\n- `variant` — group by the A/B variant served, as its index into `ab_variants` (`0`, `1`, ...); clicks sent to the default destination appear as `(default)`. The index is positional: editing `ab_variants` re-keys past clicks to whatever now sits at that index\n\nMultiple dimensions can be combined: `time,browser` returns time series broken down by browser.","examples":["time,browser","country","time,country,browser"],"title":"Group By"},"description":"Comma-separated grouping dimensions for the statistics breakdown. Defaults to `time` if omitted.\n\n**Available dimensions:**\n\n- `time` — group by time buckets (day/week/month, auto-selected based on range)\n- `browser` — group by browser name (e.g., Chrome, Firefox, Safari)\n- `os` — group by operating system (e.g., Windows, macOS, Linux)\n- `device` — group by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — group by country\n- `city` — group by city\n- `referrer` — group by referrer URL\n- `short_code` — group by URL alias\n- `utm_source` — group by the `utm_source` tag on the short link (untagged clicks appear as `(none)`)\n- `utm_medium` — group by the `utm_medium` tag\n- `utm_campaign` — group by the `utm_campaign` tag\n- `variant` — group by the A/B variant served, as its index into `ab_variants` (`0`, `1`, ...); clicks sent to the default destination appear as `(default)`. The index is positional: editing `ab_variants` re-keys past clicks to whatever now sits at that index\n\nMultiple dimensions can be combined: `time,browser` returns time series broken down by browser."},{"name":"metrics","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Comma-separated metrics to include. Defaults to `clicks,unique_clicks` if omitted.\n\n**Available metrics:**\n\n- `clicks` — total click count\n- `unique_clicks` — unique visitor count (deduplicated by IP + User-Agent)","examples":["clicks,unique_clicks","clicks"],"title":"Metrics"},"description":"Comma-separated metrics to include. Defaults to `clicks,unique_clicks` if omitted.\n\n**Available metrics:**\n\n- `clicks` — total click count\n- `unique_clicks` — unique visitor count (deduplicated by IP + User-Agent)"},{"name":"timezone","in":"query","required":false,"schema":{"type":"string","maxLength":50,"description":"IANA timezone name for time-based grouping and output formatting (e.g., `UTC`, `America/New_York`, `Asia/Kolkata`). Defaults to `UTC`.","examples":["UTC","America/New_York"],"default":"UTC","title":"Timezone"},"description":"IANA timezone name for time-based grouping and output formatting (e.g., `UTC`, `America/New_York`, `Asia/Kolkata`). Defaults to `UTC`."},{"name":"filters","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"description":"**Method 1: JSON Filters Object**\n\nJSON string containing dimension filters. Format: `{\"dimension\": [\"value1\", \"value2\"]}`\n\n**Available filter dimensions:**\n\n- `browser` — Filter by browser name (e.g., Chrome, Firefox, Safari, Edge)\n- `os` — Filter by operating system (e.g., Windows, macOS, Linux, iOS, Android)\n- `device` — Filter by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — Filter by country name (e.g., United States, Canada, Germany)\n- `city` — Filter by city name (e.g., New York, London, Mumbai)\n- `referrer` — Filter by referrer URL (e.g., https://google.com, https://twitter.com)\n- `short_code` — Filter by URL alias (e.g., mylink, promo2024)\n- `url_id` — Filter by URL id (MongoDB ObjectId); ids you do not own match nothing\n- `tag` / `tag_id` — Filter by link tag (name or id); clicks on your links carrying any listed tag\n- `utm_source` / `utm_medium` / `utm_campaign` — Filter by campaign tags; `(none)` matches untagged clicks\n- `variant` — Filter by A/B variant index (`0`, `1`, ...); `(default)` matches clicks sent to the default destination\n\n**Value format:** Array of strings for each dimension.\n\n**Important:** Filter values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Examples:**\n\n- `{\"browser\": [\"Chrome\", \"Firefox\"]}` — Chrome OR Firefox clicks\n- `{\"country\": [\"United States\", \"Canada\"], \"browser\": [\"Chrome\"]}` — US/CA clicks from Chrome\n- `{\"short_code\": [\"link1\", \"link2\"]}` — Stats for specific URLs\n\n**Alternative:** You can also pass filters as individual query parameters (see `browser`, `os`, `country`, `city`, `referrer` parameters below).","examples":["{\"browser\":[\"Chrome\",\"Firefox\"]}","{\"country\":[\"United States\",\"Canada\"],\"browser\":[\"Chrome\"]}"],"title":"Filters"},"description":"**Method 1: JSON Filters Object**\n\nJSON string containing dimension filters. Format: `{\"dimension\": [\"value1\", \"value2\"]}`\n\n**Available filter dimensions:**\n\n- `browser` — Filter by browser name (e.g., Chrome, Firefox, Safari, Edge)\n- `os` — Filter by operating system (e.g., Windows, macOS, Linux, iOS, Android)\n- `device` — Filter by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — Filter by country name (e.g., United States, Canada, Germany)\n- `city` — Filter by city name (e.g., New York, London, Mumbai)\n- `referrer` — Filter by referrer URL (e.g., https://google.com, https://twitter.com)\n- `short_code` — Filter by URL alias (e.g., mylink, promo2024)\n- `url_id` — Filter by URL id (MongoDB ObjectId); ids you do not own match nothing\n- `tag` / `tag_id` — Filter by link tag (name or id); clicks on your links carrying any listed tag\n- `utm_source` / `utm_medium` / `utm_campaign` — Filter by campaign tags; `(none)` matches untagged clicks\n- `variant` — Filter by A/B variant index (`0`, `1`, ...); `(default)` matches clicks sent to the default destination\n\n**Value format:** Array of strings for each dimension.\n\n**Important:** Filter values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Examples:**\n\n- `{\"browser\": [\"Chrome\", \"Firefox\"]}` — Chrome OR Firefox clicks\n- `{\"country\": [\"United States\", \"Canada\"], \"browser\": [\"Chrome\"]}` — US/CA clicks from Chrome\n- `{\"short_code\": [\"link1\", \"link2\"]}` — Stats for specific URLs\n\n**Alternative:** You can also pass filters as individual query parameters (see `browser`, `os`, `country`, `city`, `referrer` parameters below)."},{"name":"browser","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated browser names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Chrome, Firefox, Safari, Edge, Opera, Samsung Internet.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["Chrome,Firefox"],"title":"Browser"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated browser names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Chrome, Firefox, Safari, Edge, Opera, Samsung Internet.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"os","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated operating system names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Windows, macOS, Linux, iOS, Android, Chrome OS.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["Windows,macOS"],"title":"Os"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated operating system names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Windows, macOS, Linux, iOS, Android, Chrome OS.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"device","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated device types. Alternative to using the `filters` JSON parameter.\n\n**Values:** `mobile`, `tablet`, `desktop`, `unknown`. `unknown` also matches clicks recorded before device tracking existed.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["mobile,desktop"],"title":"Device"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated device types. Alternative to using the `filters` JSON parameter.\n\n**Values:** `mobile`, `tablet`, `desktop`, `unknown`. `unknown` also matches clicks recorded before device tracking existed.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated country names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use full country names as stored in the database (e.g., United States, Canada, United Kingdom, India, Germany, France, Japan).\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["United States,Germany"],"title":"Country"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated country names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use full country names as stored in the database (e.g., United States, Canada, United Kingdom, India, Germany, France, Japan).\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"city","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated city names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["San Francisco,Berlin"],"title":"City"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated city names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"referrer","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated referrer URLs. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Include the full URL including protocol.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["https://google.com,https://twitter.com"],"title":"Referrer"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated referrer URLs. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Include the full URL including protocol.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_source","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["newsletter,twitter"],"title":"Utm Source"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_medium","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["email,social"],"title":"Utm Medium"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_campaign","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["summer-launch"],"title":"Utm Campaign"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"variant","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated A/B variant indices (`0`, `1`, ...). `(default)` matches clicks sent to the default destination, including every click on a link without variants.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["0,1","(default)"],"title":"Variant"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated A/B variant indices (`0`, `1`, ...). `(default)` matches clicks sent to the default destination, including every click on a link without variants.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"short_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Comma-separated URL aliases to filter stats to specific URLs you own. Slices your own aggregate — aliases you do not own simply match nothing.\n\nFor statistics on a single link, prefer `GET /api/v1/stats/links/{url_id}`.","examples":["mylink"],"title":"Short Code"},"description":"Comma-separated URL aliases to filter stats to specific URLs you own. Slices your own aggregate — aliases you do not own simply match nothing.\n\nFor statistics on a single link, prefer `GET /api/v1/stats/links/{url_id}`."},{"name":"url_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Comma-separated URL ids (MongoDB ObjectIds) to filter stats to specific URLs you own. Slices your own aggregate — ids you do not own simply match nothing.\n\nFor statistics on a single link, prefer `GET /api/v1/stats/links/{url_id}`.","examples":["686cbf34cc37ed6bbcd82ab9"],"title":"Url Id"},"description":"Comma-separated URL ids (MongoDB ObjectIds) to filter stats to specific URLs you own. Slices your own aggregate — ids you do not own simply match nothing.\n\nFor statistics on a single link, prefer `GET /api/v1/stats/links/{url_id}`."},{"name":"tag","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Comma-separated tag names. Scopes the aggregate to clicks on your links carrying at least one of them (resolved to link ids at query time, so a tag added today covers the link's whole click history). Filter only: `tag` is not a `group_by` dimension. See also `tag_id`.","examples":["launch,q3"],"title":"Tag"},"description":"Comma-separated tag names. Scopes the aggregate to clicks on your links carrying at least one of them (resolved to link ids at query time, so a tag added today covers the link's whole click history). Filter only: `tag` is not a `group_by` dimension. See also `tag_id`."},{"name":"tag_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Comma-separated tag ids (from `GET /api/v1/tags`). Same scope as `tag`, by id. Filter only.","examples":["665f0c2f9e7a4b1d2c3d4e5f"],"title":"Tag Id"},"description":"Comma-separated tag ids (from `GET /api/v1/tags`). Same scope as `tag`, by id. Filter only."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats/links/{url_id}":{"get":{"tags":["Statistics"],"summary":"Link Statistics","description":"Get click statistics for a single URL you own.\n\nThe same aggregated analytics as `GET /stats`, pre-scoped to one link —\nthe response additionally echoes the link's `url_id` and `alias`.\nCustom-domain links are safe here: clicks are matched by URL id, so a\nsame-alias link on another domain can never bleed in.\n\n**Authentication**: Required — you must own the URL.\n\n**API Key Scope**: `stats:read`, `urls:read`, or `admin:all`\n\n**Rate Limits**: 60/min, 5,000/day\n\n**Grouping Dimensions**: `time`, `browser`, `os`, `device`, `country`,\n`city`, `referrer`, `utm_source`, `utm_medium`, `utm_campaign`, `variant`\n\n**Metrics**: `clicks`, `unique_clicks`\n\n**Filtering**: Filter by `browser`, `os`, `device`, `country`, `city`,\n`referrer`, `variant`, or the `utm_*` tags using query params or a JSON\n`filters` object. Link-identity filters (`short_code`, `url_id`) do not exist\nhere — the path already selects the link.\n\n**Errors**:\n\n- `400` — malformed id (not a valid ObjectId)\n- `404` — no URL with that id in your account. A URL owned by someone\n  else answers identically; this endpoint never confirms foreign ids.","operationId":"getLinkStats","parameters":[{"name":"url_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the URL (MongoDB ObjectId).","title":"Url Id"},"description":"Unique identifier of the URL (MongoDB ObjectId)."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Start of time range. Accepts ISO 8601 datetime string (e.g., `2025-01-01T00:00:00Z`) or Unix timestamp in seconds (e.g., `1735689600`). If omitted, defaults to 7 days before `end_date`.","examples":["2025-01-01T00:00:00Z"],"title":"Start Date"},"description":"Start of time range. Accepts ISO 8601 datetime string (e.g., `2025-01-01T00:00:00Z`) or Unix timestamp in seconds (e.g., `1735689600`). If omitted, defaults to 7 days before `end_date`."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"End of time range. Accepts ISO 8601 datetime string (e.g., `2025-12-31T23:59:59Z`) or Unix timestamp in seconds (e.g., `1767225599`). If omitted, defaults to now.","examples":["2025-12-31T23:59:59Z"],"title":"End Date"},"description":"End of time range. Accepts ISO 8601 datetime string (e.g., `2025-12-31T23:59:59Z`) or Unix timestamp in seconds (e.g., `1767225599`). If omitted, defaults to now."},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Comma-separated grouping dimensions for the statistics breakdown. Defaults to `time` if omitted.\n\n**Available dimensions:**\n\n- `time` — group by time buckets (day/week/month, auto-selected based on range)\n- `browser` — group by browser name (e.g., Chrome, Firefox, Safari)\n- `os` — group by operating system (e.g., Windows, macOS, Linux)\n- `device` — group by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — group by country\n- `city` — group by city\n- `referrer` — group by referrer URL\n- `utm_source` — group by the `utm_source` tag on the short link (untagged clicks appear as `(none)`)\n- `utm_medium` — group by the `utm_medium` tag\n- `utm_campaign` — group by the `utm_campaign` tag\n- `variant` — group by the A/B variant served, as its index into `ab_variants` (`0`, `1`, ...); clicks sent to the default destination appear as `(default)`. The index is positional: editing `ab_variants` re-keys past clicks to whatever now sits at that index\n\nMultiple dimensions can be combined: `time,browser` returns time series broken down by browser.","examples":["time,browser","country","time,country,browser"],"title":"Group By"},"description":"Comma-separated grouping dimensions for the statistics breakdown. Defaults to `time` if omitted.\n\n**Available dimensions:**\n\n- `time` — group by time buckets (day/week/month, auto-selected based on range)\n- `browser` — group by browser name (e.g., Chrome, Firefox, Safari)\n- `os` — group by operating system (e.g., Windows, macOS, Linux)\n- `device` — group by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — group by country\n- `city` — group by city\n- `referrer` — group by referrer URL\n- `utm_source` — group by the `utm_source` tag on the short link (untagged clicks appear as `(none)`)\n- `utm_medium` — group by the `utm_medium` tag\n- `utm_campaign` — group by the `utm_campaign` tag\n- `variant` — group by the A/B variant served, as its index into `ab_variants` (`0`, `1`, ...); clicks sent to the default destination appear as `(default)`. The index is positional: editing `ab_variants` re-keys past clicks to whatever now sits at that index\n\nMultiple dimensions can be combined: `time,browser` returns time series broken down by browser."},{"name":"metrics","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Comma-separated metrics to include. Defaults to `clicks,unique_clicks` if omitted.\n\n**Available metrics:**\n\n- `clicks` — total click count\n- `unique_clicks` — unique visitor count (deduplicated by IP + User-Agent)","examples":["clicks,unique_clicks","clicks"],"title":"Metrics"},"description":"Comma-separated metrics to include. Defaults to `clicks,unique_clicks` if omitted.\n\n**Available metrics:**\n\n- `clicks` — total click count\n- `unique_clicks` — unique visitor count (deduplicated by IP + User-Agent)"},{"name":"timezone","in":"query","required":false,"schema":{"type":"string","maxLength":50,"description":"IANA timezone name for time-based grouping and output formatting (e.g., `UTC`, `America/New_York`, `Asia/Kolkata`). Defaults to `UTC`.","examples":["UTC","America/New_York"],"default":"UTC","title":"Timezone"},"description":"IANA timezone name for time-based grouping and output formatting (e.g., `UTC`, `America/New_York`, `Asia/Kolkata`). Defaults to `UTC`."},{"name":"filters","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"description":"**Method 1: JSON Filters Object**\n\nJSON string containing dimension filters. Format: `{\"dimension\": [\"value1\", \"value2\"]}`\n\n**Available filter dimensions:**\n\n- `browser` — Filter by browser name (e.g., Chrome, Firefox, Safari, Edge)\n- `os` — Filter by operating system (e.g., Windows, macOS, Linux, iOS, Android)\n- `device` — Filter by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — Filter by country name (e.g., United States, Canada, Germany)\n- `city` — Filter by city name (e.g., New York, London, Mumbai)\n- `referrer` — Filter by referrer URL (e.g., https://google.com, https://twitter.com)\n- `utm_source` / `utm_medium` / `utm_campaign` — Filter by campaign tags; `(none)` matches untagged clicks\n- `variant` — Filter by A/B variant index (`0`, `1`, ...); `(default)` matches clicks sent to the default destination\n\n**Value format:** Array of strings for each dimension.\n\n**Important:** Filter values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Examples:**\n\n- `{\"browser\": [\"Chrome\", \"Firefox\"]}` — Chrome OR Firefox clicks\n- `{\"country\": [\"United States\", \"Canada\"], \"browser\": [\"Chrome\"]}` — US/CA clicks from Chrome\n\n**Alternative:** You can also pass filters as individual query parameters (see `browser`, `os`, `country`, `city`, `referrer` parameters below).","examples":["{\"browser\":[\"Chrome\",\"Firefox\"]}","{\"country\":[\"United States\",\"Canada\"],\"browser\":[\"Chrome\"]}"],"title":"Filters"},"description":"**Method 1: JSON Filters Object**\n\nJSON string containing dimension filters. Format: `{\"dimension\": [\"value1\", \"value2\"]}`\n\n**Available filter dimensions:**\n\n- `browser` — Filter by browser name (e.g., Chrome, Firefox, Safari, Edge)\n- `os` — Filter by operating system (e.g., Windows, macOS, Linux, iOS, Android)\n- `device` — Filter by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — Filter by country name (e.g., United States, Canada, Germany)\n- `city` — Filter by city name (e.g., New York, London, Mumbai)\n- `referrer` — Filter by referrer URL (e.g., https://google.com, https://twitter.com)\n- `utm_source` / `utm_medium` / `utm_campaign` — Filter by campaign tags; `(none)` matches untagged clicks\n- `variant` — Filter by A/B variant index (`0`, `1`, ...); `(default)` matches clicks sent to the default destination\n\n**Value format:** Array of strings for each dimension.\n\n**Important:** Filter values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Examples:**\n\n- `{\"browser\": [\"Chrome\", \"Firefox\"]}` — Chrome OR Firefox clicks\n- `{\"country\": [\"United States\", \"Canada\"], \"browser\": [\"Chrome\"]}` — US/CA clicks from Chrome\n\n**Alternative:** You can also pass filters as individual query parameters (see `browser`, `os`, `country`, `city`, `referrer` parameters below)."},{"name":"browser","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated browser names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Chrome, Firefox, Safari, Edge, Opera, Samsung Internet.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["Chrome,Firefox"],"title":"Browser"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated browser names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Chrome, Firefox, Safari, Edge, Opera, Samsung Internet.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"os","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated operating system names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Windows, macOS, Linux, iOS, Android, Chrome OS.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["Windows,macOS"],"title":"Os"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated operating system names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Windows, macOS, Linux, iOS, Android, Chrome OS.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"device","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated device types. Alternative to using the `filters` JSON parameter.\n\n**Values:** `mobile`, `tablet`, `desktop`, `unknown`. `unknown` also matches clicks recorded before device tracking existed.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["mobile,desktop"],"title":"Device"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated device types. Alternative to using the `filters` JSON parameter.\n\n**Values:** `mobile`, `tablet`, `desktop`, `unknown`. `unknown` also matches clicks recorded before device tracking existed.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated country names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use full country names as stored in the database (e.g., United States, Canada, United Kingdom, India, Germany, France, Japan).\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["United States,Germany"],"title":"Country"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated country names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use full country names as stored in the database (e.g., United States, Canada, United Kingdom, India, Germany, France, Japan).\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"city","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated city names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["San Francisco,Berlin"],"title":"City"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated city names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"referrer","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated referrer URLs. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Include the full URL including protocol.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["https://google.com,https://twitter.com"],"title":"Referrer"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated referrer URLs. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Include the full URL including protocol.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_source","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["newsletter,twitter"],"title":"Utm Source"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_medium","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["email,social"],"title":"Utm Medium"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_campaign","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["summer-launch"],"title":"Utm Campaign"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"variant","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated A/B variant indices (`0`, `1`, ...). `(default)` matches clicks sent to the default destination, including every click on a link without variants.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["0,1","(default)"],"title":"Variant"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated A/B variant indices (`0`, `1`, ...). `(default)` matches clicks sent to the default destination, including every click on a link without variants.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkStatsResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/stats/{short_code}":{"get":{"tags":["Public"],"summary":"Public URL Statistics","description":"Get public click statistics for a single short link.\n\nResolves both URL generations (plus emoji aliases) on the system\ndefault domain and returns link facts plus the standard stats wire.\n\n**Authentication**: Optional — an owner session additionally sees\nprivate-stats links and skips the password gate.\n\n**Privacy**: A link with private stats answers exactly like a missing\ncode (404, byte-identical). Password-protected links answer 401\n`password_required`; send the password via POST — never in the URL.\n\n**Rate Limits**:\n\n- Authenticated: 60/min, 2,000/day\n- Anonymous: 20/min, 500/day","operationId":"getPublicStats","parameters":[{"name":"short_code","in":"path","required":true,"schema":{"type":"string","title":"Short Code"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Range start (ISO 8601). Defaults to 7 days before end_date.","examples":["2025-01-01T00:00:00Z"],"title":"Start Date"},"description":"Range start (ISO 8601). Defaults to 7 days before end_date."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Range end (ISO 8601). Defaults to now.","examples":["2025-12-31T23:59:59Z"],"title":"End Date"},"description":"Range end (ISO 8601). Defaults to now."},{"name":"timezone","in":"query","required":false,"schema":{"type":"string","maxLength":50,"description":"IANA timezone for time bucketing and formatting.","examples":["UTC","America/New_York"],"default":"UTC","title":"Timezone"},"description":"IANA timezone for time bucketing and formatting."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicStatsResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{},{"ApiKeyAuth":[]},{"JWTAuth":[]}]},"post":{"tags":["Public"],"summary":"Public URL Statistics (password unlock)","description":"Same as the GET variant, carrying a password in the JSON body.\n\nThe body is the ONLY way a password travels to this endpoint —\nquery-string passwords are ignored so they can't land in URLs, logs,\nor referrers. Wrong passwords answer 401 `invalid_password`\n(retryable). The body may be absent or empty.","operationId":"getPublicStatsWithPassword","parameters":[{"name":"short_code","in":"path","required":true,"schema":{"type":"string","title":"Short Code"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Range start (ISO 8601). Defaults to 7 days before end_date.","examples":["2025-01-01T00:00:00Z"],"title":"Start Date"},"description":"Range start (ISO 8601). Defaults to 7 days before end_date."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Range end (ISO 8601). Defaults to now.","examples":["2025-12-31T23:59:59Z"],"title":"End Date"},"description":"Range end (ISO 8601). Defaults to now."},{"name":"timezone","in":"query","required":false,"schema":{"type":"string","maxLength":50,"description":"IANA timezone for time bucketing and formatting.","examples":["UTC","America/New_York"],"default":"UTC","title":"Timezone"},"description":"IANA timezone for time bucketing and formatting."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PublicStatsBody"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicStatsResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{},{"ApiKeyAuth":[]},{"JWTAuth":[]}]}},"/api/v1/export":{"get":{"tags":["Statistics"],"summary":"Export Statistics","description":"Export click statistics across all URLs you own as a downloadable file.\n\nGenerate a file export of click analytics data in the specified format.\nThe response is a binary download with appropriate `Content-Disposition` header.\n\n**Authentication**: Required.\n\n**API Key Scope**: `stats:read`, `urls:read`, or `admin:all`\n\n**Rate Limits**: 30/min, 1,000/day\n\n**Export Formats**:\n\n- `json` — single JSON file\n- `xml` — single XML file\n- `xlsx` — Excel spreadsheet with multiple sheets\n- `csv` — **ZIP archive** containing `summary.csv` plus one CSV file per metrics dimension\n\n**Filtering**: Same as `GET /stats` — including the `url_id` filter to\nslice the export to specific URLs you own. To export a single link,\nprefer `GET /export/links/{url_id}`.\n\n**Note**: Export generation is resource-intensive. Lower rate limits apply\ncompared to other endpoints.","operationId":"exportStats","parameters":[{"name":"format","in":"query","required":true,"schema":{"enum":["csv","xlsx","json","xml"],"type":"string","description":"Export file format.","title":"Format"},"description":"Export file format."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Start of time range. Accepts ISO 8601 datetime string (e.g., `2025-01-01T00:00:00Z`) or Unix timestamp in seconds (e.g., `1735689600`). If omitted, defaults to 7 days before `end_date`.","examples":["2025-01-01T00:00:00Z"],"title":"Start Date"},"description":"Start of time range. Accepts ISO 8601 datetime string (e.g., `2025-01-01T00:00:00Z`) or Unix timestamp in seconds (e.g., `1735689600`). If omitted, defaults to 7 days before `end_date`."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"End of time range. Accepts ISO 8601 datetime string (e.g., `2025-12-31T23:59:59Z`) or Unix timestamp in seconds (e.g., `1767225599`). If omitted, defaults to now.","examples":["2025-12-31T23:59:59Z"],"title":"End Date"},"description":"End of time range. Accepts ISO 8601 datetime string (e.g., `2025-12-31T23:59:59Z`) or Unix timestamp in seconds (e.g., `1767225599`). If omitted, defaults to now."},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Comma-separated grouping dimensions for the statistics breakdown. Defaults to `time` if omitted.\n\n**Available dimensions:**\n\n- `time` — group by time buckets (day/week/month, auto-selected based on range)\n- `browser` — group by browser name (e.g., Chrome, Firefox, Safari)\n- `os` — group by operating system (e.g., Windows, macOS, Linux)\n- `device` — group by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — group by country\n- `city` — group by city\n- `referrer` — group by referrer URL\n- `short_code` — group by URL alias\n- `utm_source` — group by the `utm_source` tag on the short link (untagged clicks appear as `(none)`)\n- `utm_medium` — group by the `utm_medium` tag\n- `utm_campaign` — group by the `utm_campaign` tag\n- `variant` — group by the A/B variant served, as its index into `ab_variants` (`0`, `1`, ...); clicks sent to the default destination appear as `(default)`. The index is positional: editing `ab_variants` re-keys past clicks to whatever now sits at that index\n\nMultiple dimensions can be combined: `time,browser` returns time series broken down by browser.","examples":["time,browser","country","time,country,browser"],"title":"Group By"},"description":"Comma-separated grouping dimensions for the statistics breakdown. Defaults to `time` if omitted.\n\n**Available dimensions:**\n\n- `time` — group by time buckets (day/week/month, auto-selected based on range)\n- `browser` — group by browser name (e.g., Chrome, Firefox, Safari)\n- `os` — group by operating system (e.g., Windows, macOS, Linux)\n- `device` — group by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — group by country\n- `city` — group by city\n- `referrer` — group by referrer URL\n- `short_code` — group by URL alias\n- `utm_source` — group by the `utm_source` tag on the short link (untagged clicks appear as `(none)`)\n- `utm_medium` — group by the `utm_medium` tag\n- `utm_campaign` — group by the `utm_campaign` tag\n- `variant` — group by the A/B variant served, as its index into `ab_variants` (`0`, `1`, ...); clicks sent to the default destination appear as `(default)`. The index is positional: editing `ab_variants` re-keys past clicks to whatever now sits at that index\n\nMultiple dimensions can be combined: `time,browser` returns time series broken down by browser."},{"name":"metrics","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Comma-separated metrics to include. Defaults to `clicks,unique_clicks` if omitted.\n\n**Available metrics:**\n\n- `clicks` — total click count\n- `unique_clicks` — unique visitor count (deduplicated by IP + User-Agent)","examples":["clicks,unique_clicks","clicks"],"title":"Metrics"},"description":"Comma-separated metrics to include. Defaults to `clicks,unique_clicks` if omitted.\n\n**Available metrics:**\n\n- `clicks` — total click count\n- `unique_clicks` — unique visitor count (deduplicated by IP + User-Agent)"},{"name":"timezone","in":"query","required":false,"schema":{"type":"string","maxLength":50,"description":"IANA timezone name for time-based grouping and output formatting (e.g., `UTC`, `America/New_York`, `Asia/Kolkata`). Defaults to `UTC`.","examples":["UTC","America/New_York"],"default":"UTC","title":"Timezone"},"description":"IANA timezone name for time-based grouping and output formatting (e.g., `UTC`, `America/New_York`, `Asia/Kolkata`). Defaults to `UTC`."},{"name":"filters","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"description":"**Method 1: JSON Filters Object**\n\nJSON string containing dimension filters. Format: `{\"dimension\": [\"value1\", \"value2\"]}`\n\n**Available filter dimensions:**\n\n- `browser` — Filter by browser name (e.g., Chrome, Firefox, Safari, Edge)\n- `os` — Filter by operating system (e.g., Windows, macOS, Linux, iOS, Android)\n- `device` — Filter by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — Filter by country name (e.g., United States, Canada, Germany)\n- `city` — Filter by city name (e.g., New York, London, Mumbai)\n- `referrer` — Filter by referrer URL (e.g., https://google.com, https://twitter.com)\n- `short_code` — Filter by URL alias (e.g., mylink, promo2024)\n- `url_id` — Filter by URL id (MongoDB ObjectId); ids you do not own match nothing\n- `tag` / `tag_id` — Filter by link tag (name or id); clicks on your links carrying any listed tag\n- `utm_source` / `utm_medium` / `utm_campaign` — Filter by campaign tags; `(none)` matches untagged clicks\n- `variant` — Filter by A/B variant index (`0`, `1`, ...); `(default)` matches clicks sent to the default destination\n\n**Value format:** Array of strings for each dimension.\n\n**Important:** Filter values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Examples:**\n\n- `{\"browser\": [\"Chrome\", \"Firefox\"]}` — Chrome OR Firefox clicks\n- `{\"country\": [\"United States\", \"Canada\"], \"browser\": [\"Chrome\"]}` — US/CA clicks from Chrome\n- `{\"short_code\": [\"link1\", \"link2\"]}` — Stats for specific URLs\n\n**Alternative:** You can also pass filters as individual query parameters (see `browser`, `os`, `country`, `city`, `referrer` parameters below).","examples":["{\"browser\":[\"Chrome\",\"Firefox\"]}","{\"country\":[\"United States\",\"Canada\"],\"browser\":[\"Chrome\"]}"],"title":"Filters"},"description":"**Method 1: JSON Filters Object**\n\nJSON string containing dimension filters. Format: `{\"dimension\": [\"value1\", \"value2\"]}`\n\n**Available filter dimensions:**\n\n- `browser` — Filter by browser name (e.g., Chrome, Firefox, Safari, Edge)\n- `os` — Filter by operating system (e.g., Windows, macOS, Linux, iOS, Android)\n- `device` — Filter by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — Filter by country name (e.g., United States, Canada, Germany)\n- `city` — Filter by city name (e.g., New York, London, Mumbai)\n- `referrer` — Filter by referrer URL (e.g., https://google.com, https://twitter.com)\n- `short_code` — Filter by URL alias (e.g., mylink, promo2024)\n- `url_id` — Filter by URL id (MongoDB ObjectId); ids you do not own match nothing\n- `tag` / `tag_id` — Filter by link tag (name or id); clicks on your links carrying any listed tag\n- `utm_source` / `utm_medium` / `utm_campaign` — Filter by campaign tags; `(none)` matches untagged clicks\n- `variant` — Filter by A/B variant index (`0`, `1`, ...); `(default)` matches clicks sent to the default destination\n\n**Value format:** Array of strings for each dimension.\n\n**Important:** Filter values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Examples:**\n\n- `{\"browser\": [\"Chrome\", \"Firefox\"]}` — Chrome OR Firefox clicks\n- `{\"country\": [\"United States\", \"Canada\"], \"browser\": [\"Chrome\"]}` — US/CA clicks from Chrome\n- `{\"short_code\": [\"link1\", \"link2\"]}` — Stats for specific URLs\n\n**Alternative:** You can also pass filters as individual query parameters (see `browser`, `os`, `country`, `city`, `referrer` parameters below)."},{"name":"browser","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated browser names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Chrome, Firefox, Safari, Edge, Opera, Samsung Internet.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["Chrome,Firefox"],"title":"Browser"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated browser names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Chrome, Firefox, Safari, Edge, Opera, Samsung Internet.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"os","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated operating system names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Windows, macOS, Linux, iOS, Android, Chrome OS.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["Windows,macOS"],"title":"Os"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated operating system names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Windows, macOS, Linux, iOS, Android, Chrome OS.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"device","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated device types. Alternative to using the `filters` JSON parameter.\n\n**Values:** `mobile`, `tablet`, `desktop`, `unknown`. `unknown` also matches clicks recorded before device tracking existed.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["mobile,desktop"],"title":"Device"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated device types. Alternative to using the `filters` JSON parameter.\n\n**Values:** `mobile`, `tablet`, `desktop`, `unknown`. `unknown` also matches clicks recorded before device tracking existed.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated country names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use full country names as stored in the database (e.g., United States, Canada, United Kingdom, India, Germany, France, Japan).\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["United States,Germany"],"title":"Country"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated country names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use full country names as stored in the database (e.g., United States, Canada, United Kingdom, India, Germany, France, Japan).\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"city","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated city names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["San Francisco,Berlin"],"title":"City"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated city names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"referrer","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated referrer URLs. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Include the full URL including protocol.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["https://google.com,https://twitter.com"],"title":"Referrer"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated referrer URLs. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Include the full URL including protocol.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_source","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["newsletter,twitter"],"title":"Utm Source"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_medium","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["email,social"],"title":"Utm Medium"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_campaign","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["summer-launch"],"title":"Utm Campaign"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"variant","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated A/B variant indices (`0`, `1`, ...). `(default)` matches clicks sent to the default destination, including every click on a link without variants.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["0,1","(default)"],"title":"Variant"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated A/B variant indices (`0`, `1`, ...). `(default)` matches clicks sent to the default destination, including every click on a link without variants.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"short_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Comma-separated URL aliases to filter stats to specific URLs you own. Slices your own aggregate — aliases you do not own simply match nothing.\n\nFor statistics on a single link, prefer `GET /api/v1/stats/links/{url_id}`.","examples":["mylink"],"title":"Short Code"},"description":"Comma-separated URL aliases to filter stats to specific URLs you own. Slices your own aggregate — aliases you do not own simply match nothing.\n\nFor statistics on a single link, prefer `GET /api/v1/stats/links/{url_id}`."},{"name":"url_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Comma-separated URL ids (MongoDB ObjectIds) to filter stats to specific URLs you own. Slices your own aggregate — ids you do not own simply match nothing.\n\nFor statistics on a single link, prefer `GET /api/v1/stats/links/{url_id}`.","examples":["686cbf34cc37ed6bbcd82ab9"],"title":"Url Id"},"description":"Comma-separated URL ids (MongoDB ObjectIds) to filter stats to specific URLs you own. Slices your own aggregate — ids you do not own simply match nothing.\n\nFor statistics on a single link, prefer `GET /api/v1/stats/links/{url_id}`."},{"name":"tag","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Comma-separated tag names. Scopes the aggregate to clicks on your links carrying at least one of them (resolved to link ids at query time, so a tag added today covers the link's whole click history). Filter only: `tag` is not a `group_by` dimension. See also `tag_id`.","examples":["launch,q3"],"title":"Tag"},"description":"Comma-separated tag names. Scopes the aggregate to clicks on your links carrying at least one of them (resolved to link ids at query time, so a tag added today covers the link's whole click history). Filter only: `tag` is not a `group_by` dimension. See also `tag_id`."},{"name":"tag_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Comma-separated tag ids (from `GET /api/v1/tags`). Same scope as `tag`, by id. Filter only.","examples":["665f0c2f9e7a4b1d2c3d4e5f"],"title":"Tag Id"},"description":"Comma-separated tag ids (from `GET /api/v1/tags`). Same scope as `tag`, by id. Filter only."}],"responses":{"200":{"description":"Export file download","content":{"application/json":{"schema":{"type":"string","format":"binary"}},"application/xml":{"schema":{"type":"string","format":"binary"}},"application/zip":{"schema":{"type":"string","format":"binary"},"x-description":"CSV export — ZIP archive containing summary.csv plus one file per dimension"},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"},"x-description":"XLSX export — Excel workbook with multiple sheets"}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error — export generation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/export/links/{url_id}":{"get":{"tags":["Statistics"],"summary":"Export Link Statistics","description":"Export click statistics for a single URL you own.\n\nThe export twin of `GET /stats/links/{url_id}` — the same formats as\n`GET /export`, pre-scoped to one link. The suggested filename carries\nthe link's alias.\n\n**Authentication**: Required — you must own the URL.\n\n**API Key Scope**: `stats:read`, `urls:read`, or `admin:all`\n\n**Rate Limits**: 30/min, 1,000/day\n\n**Export Formats**:\n\n- `json` — single JSON file\n- `xml` — single XML file\n- `xlsx` — Excel spreadsheet with multiple sheets\n- `csv` — **ZIP archive** containing `summary.csv` plus one CSV file per metrics dimension\n\n**Errors**:\n\n- `400` — malformed id (not a valid ObjectId)\n- `404` — no URL with that id in your account. A URL owned by someone\n  else answers identically; this endpoint never confirms foreign ids.\n\n**Note**: Export generation is resource-intensive. Lower rate limits apply\ncompared to other endpoints.","operationId":"exportLinkStats","parameters":[{"name":"url_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the URL (MongoDB ObjectId).","title":"Url Id"},"description":"Unique identifier of the URL (MongoDB ObjectId)."},{"name":"format","in":"query","required":true,"schema":{"enum":["csv","xlsx","json","xml"],"type":"string","description":"Export file format.","title":"Format"},"description":"Export file format."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Start of time range. Accepts ISO 8601 datetime string (e.g., `2025-01-01T00:00:00Z`) or Unix timestamp in seconds (e.g., `1735689600`). If omitted, defaults to 7 days before `end_date`.","examples":["2025-01-01T00:00:00Z"],"title":"Start Date"},"description":"Start of time range. Accepts ISO 8601 datetime string (e.g., `2025-01-01T00:00:00Z`) or Unix timestamp in seconds (e.g., `1735689600`). If omitted, defaults to 7 days before `end_date`."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"End of time range. Accepts ISO 8601 datetime string (e.g., `2025-12-31T23:59:59Z`) or Unix timestamp in seconds (e.g., `1767225599`). If omitted, defaults to now.","examples":["2025-12-31T23:59:59Z"],"title":"End Date"},"description":"End of time range. Accepts ISO 8601 datetime string (e.g., `2025-12-31T23:59:59Z`) or Unix timestamp in seconds (e.g., `1767225599`). If omitted, defaults to now."},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Comma-separated grouping dimensions for the statistics breakdown. Defaults to `time` if omitted.\n\n**Available dimensions:**\n\n- `time` — group by time buckets (day/week/month, auto-selected based on range)\n- `browser` — group by browser name (e.g., Chrome, Firefox, Safari)\n- `os` — group by operating system (e.g., Windows, macOS, Linux)\n- `device` — group by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — group by country\n- `city` — group by city\n- `referrer` — group by referrer URL\n- `utm_source` — group by the `utm_source` tag on the short link (untagged clicks appear as `(none)`)\n- `utm_medium` — group by the `utm_medium` tag\n- `utm_campaign` — group by the `utm_campaign` tag\n- `variant` — group by the A/B variant served, as its index into `ab_variants` (`0`, `1`, ...); clicks sent to the default destination appear as `(default)`. The index is positional: editing `ab_variants` re-keys past clicks to whatever now sits at that index\n\nMultiple dimensions can be combined: `time,browser` returns time series broken down by browser.","examples":["time,browser","country","time,country,browser"],"title":"Group By"},"description":"Comma-separated grouping dimensions for the statistics breakdown. Defaults to `time` if omitted.\n\n**Available dimensions:**\n\n- `time` — group by time buckets (day/week/month, auto-selected based on range)\n- `browser` — group by browser name (e.g., Chrome, Firefox, Safari)\n- `os` — group by operating system (e.g., Windows, macOS, Linux)\n- `device` — group by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — group by country\n- `city` — group by city\n- `referrer` — group by referrer URL\n- `utm_source` — group by the `utm_source` tag on the short link (untagged clicks appear as `(none)`)\n- `utm_medium` — group by the `utm_medium` tag\n- `utm_campaign` — group by the `utm_campaign` tag\n- `variant` — group by the A/B variant served, as its index into `ab_variants` (`0`, `1`, ...); clicks sent to the default destination appear as `(default)`. The index is positional: editing `ab_variants` re-keys past clicks to whatever now sits at that index\n\nMultiple dimensions can be combined: `time,browser` returns time series broken down by browser."},{"name":"metrics","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Comma-separated metrics to include. Defaults to `clicks,unique_clicks` if omitted.\n\n**Available metrics:**\n\n- `clicks` — total click count\n- `unique_clicks` — unique visitor count (deduplicated by IP + User-Agent)","examples":["clicks,unique_clicks","clicks"],"title":"Metrics"},"description":"Comma-separated metrics to include. Defaults to `clicks,unique_clicks` if omitted.\n\n**Available metrics:**\n\n- `clicks` — total click count\n- `unique_clicks` — unique visitor count (deduplicated by IP + User-Agent)"},{"name":"timezone","in":"query","required":false,"schema":{"type":"string","maxLength":50,"description":"IANA timezone name for time-based grouping and output formatting (e.g., `UTC`, `America/New_York`, `Asia/Kolkata`). Defaults to `UTC`.","examples":["UTC","America/New_York"],"default":"UTC","title":"Timezone"},"description":"IANA timezone name for time-based grouping and output formatting (e.g., `UTC`, `America/New_York`, `Asia/Kolkata`). Defaults to `UTC`."},{"name":"filters","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"description":"**Method 1: JSON Filters Object**\n\nJSON string containing dimension filters. Format: `{\"dimension\": [\"value1\", \"value2\"]}`\n\n**Available filter dimensions:**\n\n- `browser` — Filter by browser name (e.g., Chrome, Firefox, Safari, Edge)\n- `os` — Filter by operating system (e.g., Windows, macOS, Linux, iOS, Android)\n- `device` — Filter by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — Filter by country name (e.g., United States, Canada, Germany)\n- `city` — Filter by city name (e.g., New York, London, Mumbai)\n- `referrer` — Filter by referrer URL (e.g., https://google.com, https://twitter.com)\n- `utm_source` / `utm_medium` / `utm_campaign` — Filter by campaign tags; `(none)` matches untagged clicks\n- `variant` — Filter by A/B variant index (`0`, `1`, ...); `(default)` matches clicks sent to the default destination\n\n**Value format:** Array of strings for each dimension.\n\n**Important:** Filter values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Examples:**\n\n- `{\"browser\": [\"Chrome\", \"Firefox\"]}` — Chrome OR Firefox clicks\n- `{\"country\": [\"United States\", \"Canada\"], \"browser\": [\"Chrome\"]}` — US/CA clicks from Chrome\n\n**Alternative:** You can also pass filters as individual query parameters (see `browser`, `os`, `country`, `city`, `referrer` parameters below).","examples":["{\"browser\":[\"Chrome\",\"Firefox\"]}","{\"country\":[\"United States\",\"Canada\"],\"browser\":[\"Chrome\"]}"],"title":"Filters"},"description":"**Method 1: JSON Filters Object**\n\nJSON string containing dimension filters. Format: `{\"dimension\": [\"value1\", \"value2\"]}`\n\n**Available filter dimensions:**\n\n- `browser` — Filter by browser name (e.g., Chrome, Firefox, Safari, Edge)\n- `os` — Filter by operating system (e.g., Windows, macOS, Linux, iOS, Android)\n- `device` — Filter by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n- `country` — Filter by country name (e.g., United States, Canada, Germany)\n- `city` — Filter by city name (e.g., New York, London, Mumbai)\n- `referrer` — Filter by referrer URL (e.g., https://google.com, https://twitter.com)\n- `utm_source` / `utm_medium` / `utm_campaign` — Filter by campaign tags; `(none)` matches untagged clicks\n- `variant` — Filter by A/B variant index (`0`, `1`, ...); `(default)` matches clicks sent to the default destination\n\n**Value format:** Array of strings for each dimension.\n\n**Important:** Filter values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Examples:**\n\n- `{\"browser\": [\"Chrome\", \"Firefox\"]}` — Chrome OR Firefox clicks\n- `{\"country\": [\"United States\", \"Canada\"], \"browser\": [\"Chrome\"]}` — US/CA clicks from Chrome\n\n**Alternative:** You can also pass filters as individual query parameters (see `browser`, `os`, `country`, `city`, `referrer` parameters below)."},{"name":"browser","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated browser names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Chrome, Firefox, Safari, Edge, Opera, Samsung Internet.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["Chrome,Firefox"],"title":"Browser"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated browser names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Chrome, Firefox, Safari, Edge, Opera, Samsung Internet.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"os","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated operating system names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Windows, macOS, Linux, iOS, Android, Chrome OS.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["Windows,macOS"],"title":"Os"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated operating system names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Common values include: Windows, macOS, Linux, iOS, Android, Chrome OS.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"device","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated device types. Alternative to using the `filters` JSON parameter.\n\n**Values:** `mobile`, `tablet`, `desktop`, `unknown`. `unknown` also matches clicks recorded before device tracking existed.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["mobile,desktop"],"title":"Device"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated device types. Alternative to using the `filters` JSON parameter.\n\n**Values:** `mobile`, `tablet`, `desktop`, `unknown`. `unknown` also matches clicks recorded before device tracking existed.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated country names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use full country names as stored in the database (e.g., United States, Canada, United Kingdom, India, Germany, France, Japan).\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["United States,Germany"],"title":"Country"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated country names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use full country names as stored in the database (e.g., United States, Canada, United Kingdom, India, Germany, France, Japan).\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"city","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated city names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["San Francisco,Berlin"],"title":"City"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated city names. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Use exact capitalization as stored in the database.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"referrer","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated referrer URLs. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Include the full URL including protocol.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["https://google.com,https://twitter.com"],"title":"Referrer"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated referrer URLs. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. Include the full URL including protocol.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_source","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["newsletter,twitter"],"title":"Utm Source"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_medium","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["email,social"],"title":"Utm Medium"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"utm_campaign","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["summer-launch"],"title":"Utm Campaign"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated campaign tag values. Alternative to using the `filters` JSON parameter.\n\n**Important:** Values are case-sensitive. `(none)` matches clicks with no tag.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."},{"name":"variant","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated A/B variant indices (`0`, `1`, ...). `(default)` matches clicks sent to the default destination, including every click on a link without variants.\n\n**Note:** Both `filters` JSON and individual parameters can be combined.","examples":["0,1","(default)"],"title":"Variant"},"description":"**Method 2: Individual Filter Parameter**\n\nComma-separated A/B variant indices (`0`, `1`, ...). `(default)` matches clicks sent to the default destination, including every click on a link without variants.\n\n**Note:** Both `filters` JSON and individual parameters can be combined."}],"responses":{"200":{"description":"Export file download","content":{"application/json":{"schema":{"type":"string","format":"binary"}},"application/xml":{"schema":{"type":"string","format":"binary"}},"application/zip":{"schema":{"type":"string","format":"binary"},"x-description":"CSV export — ZIP archive containing summary.csv plus one file per dimension"},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"},"x-description":"XLSX export — Excel workbook with multiple sheets"}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error — export generation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/keys":{"get":{"tags":["API Keys"],"summary":"List API Keys","description":"List all API keys for the authenticated user.\n\nReturns metadata for all API keys (both active and revoked) belonging to the\nauthenticated user. The full token value is **never** returned in this\nendpoint for security reasons — only the `token_prefix` is shown.\n\n**Authentication**: Required — interactive session or an app token with\nthe `keys:manage` scope (API keys cannot be used to manage API keys).\n\n**Rate Limits**: 60/min","operationId":"listApiKeys","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeysListResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["API Keys"],"summary":"Create API Key","description":"Create a new API key for programmatic access.\n\nGenerate a new API key with the specified name and scopes. The full token\n(prefixed with `spoo_`) is returned **only in this response** and cannot be\nretrieved again.\n\n**Authentication**: Required — interactive session only. Connected apps\nand API keys cannot create keys; minting a credential is a first-party\naction. Email must be verified.\n\n**Rate Limits**: 5/hour\n\n**Available Scopes**: `shorten:create`, `urls:manage`, `urls:read`,\n`stats:read`, `domains:manage`, `domains:read`, `reports:create`,\n`admin:all`\n\n**Notes**:\n\n- Store the returned `token` securely — it will not be shown again\n- Set `expires_at` to limit the key's lifetime (ISO 8601 or Unix epoch)\n- Omit `expires_at` for a non-expiring key","operationId":"createApiKey","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/keys/{key_id}":{"delete":{"tags":["API Keys"],"summary":"Delete/Revoke API Key","description":"Delete or revoke an API key.\n\nRemove an API key either permanently (hard delete) or by marking it as\nrevoked (soft delete). Revoked keys stop working immediately but remain\nvisible in the key list for audit purposes.\n\n**Authentication**: Required — interactive session or an app token with\nthe `keys:manage` scope (API keys cannot be used to manage API keys).\n\n**Rate Limits**: 30/min\n\n**Modes**:\n\n- `?revoke=false` (default) — **permanently deletes** the key record\n- `?revoke=true` — marks the key as revoked but preserves the record;\n  the key appears with `revoked: true` in the list endpoint","operationId":"deleteApiKey","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","minLength":24,"maxLength":24,"pattern":"^[0-9a-f]{24}$","title":"Key Id"}},{"name":"revoke","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Revoke"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyActionResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/apps":{"get":{"tags":["Apps"],"summary":"List Connected Apps","description":"List the apps connected to the authenticated user's account.\n\nReturns one entry per active device-auth grant (revoked grants are\nexcluded), newest first. `app` is the registry key from\n`config/apps.yaml` — pass it as `app_id` to `POST /auth/device/revoke`\nto disconnect an app. An empty `items` array means nothing is\nconnected.\n\n**Authentication**: Required — JWT Bearer only (API keys cannot list\nthe account's connected apps).\n\n**Rate Limits**: 60/min","operationId":"listAppGrants","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppGrantsListResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/custom-domains":{"post":{"tags":["Custom Domains"],"summary":"Register Custom Domain","description":"Register a new custom domain for branded short links.\n\nThe domain is born in `PENDING` state. The user must publish the DNS\nrecords returned in `dns_records` at their DNS provider, then call\n`POST /custom-domains/{id}/verify` to trigger verification. Cloudflare\nauto-verifies via HTTP DCV once the CNAME is live and propagated.\n\n**Authentication**: Required (JWT Bearer or API key with `domains:manage`).\n\n**Email verification**: Required (applies to API key callers too).\n\n**Feature gate**: Must be enabled for the calling user.\n\n**Rate Limits**: 10/hour (route, failed attempts count) + `max_per_user`\nowned domains (service quota, any status).","operationId":"createCustomDomain","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomDomainRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDomainResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Custom Domains"],"summary":"List Custom Domains","description":"List custom domains owned by the authenticated user.\n\nReads bypass the feature flag so owners can still see state during a\nrollback.\n\n**Authentication**: Required (JWT or API key with `domains:read`).\n\n**Rate Limits**: 60/min.\n\n**Pagination**: `page` (default 1) + `pageSize` (default 20, max 100).","operationId":"listCustomDomains","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDomainListResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/custom-domains/{domain_id}/verify":{"post":{"tags":["Custom Domains"],"summary":"Verify Custom Domain","description":"Trigger a fresh verification check for a custom domain.\n\nThe verifier dispatched depends on the chosen DCV method (CF HTTP DCV on\nCF SaaS deployments, CNAME/A/TXT on self-host). On success the domain\ntransitions to `ACTIVE` and short links on the domain start resolving.\n\n**Authentication**: Required (JWT or API key with `domains:manage`).\n\n**Rate Limits**: 10/min (route) + 60/hour per domain (service quota).","operationId":"verifyCustomDomain","parameters":[{"name":"domain_id","in":"path","required":true,"schema":{"type":"string","description":"MongoDB ObjectId of the domain.","title":"Domain Id"},"description":"MongoDB ObjectId of the domain."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDomainResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/custom-domains/{domain_id}":{"get":{"tags":["Custom Domains"],"summary":"Get Custom Domain","description":"Fetch a single custom domain owned by the caller.\n\nUsed by the dashboard detail view + auto-poll after Verify. Bypasses the\nfeature flag like other read endpoints.\n\n**Authentication**: Required (JWT or API key with `domains:read`).\n\n**Rate Limits**: 60/min.","operationId":"getCustomDomain","parameters":[{"name":"domain_id","in":"path","required":true,"schema":{"type":"string","description":"MongoDB ObjectId of the domain.","title":"Domain Id"},"description":"MongoDB ObjectId of the domain."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDomainResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Custom Domains"],"summary":"Update Custom Domain Routing","description":"Update the per-domain routing config.\n\nPartial update — send only the fields you want to change. Omit a field to\nleave it untouched. Send explicit `null` to clear a stored value. The\nconfig takes effect only when the domain is `ACTIVE`; non-ACTIVE domains\nreturn 422.\n\n**Configurable fields**:\n- `root_redirect` — destination for `GET /` (302).\n- `not_found_redirect` — fallback for any path that doesn't match an alias.\n- `custom_robots_txt` — body served at `/robots.txt` (≤4096 chars).\n\n**Authentication**: Required (JWT or API key with `domains:manage`).\n\n**Rate Limits**: 30/min.\n\n**Responses**:\n- 200 — updated; full domain response returned\n- 403 — caller does not own this domain\n- 404 — domain not found (or invalid id)\n- 422 — domain isn't ACTIVE, or body fails validation","operationId":"updateCustomDomain","parameters":[{"name":"domain_id","in":"path","required":true,"schema":{"type":"string","description":"MongoDB ObjectId of the domain.","title":"Domain Id"},"description":"MongoDB ObjectId of the domain."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomDomainRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDomainResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Custom Domains"],"summary":"Revoke Custom Domain","description":"Revoke a custom domain. `REVOKED` is terminal.\n\nWith `?cascade=true`, all URLs owned by the caller on the domain are\nbulk-deleted. With `?cascade=false` (default), URLs remain in the\ndatabase and the domain stops serving — the URLs effectively become\norphans until the domain is re-registered or garbage-collected.\n\n**Authentication**: Required (JWT or API key with `domains:manage`).\n\n**Rate Limits**: 10/min.","operationId":"deleteCustomDomain","parameters":[{"name":"domain_id","in":"path","required":true,"schema":{"type":"string","description":"MongoDB ObjectId of the domain.","title":"Domain Id"},"description":"MongoDB ObjectId of the domain."},{"name":"cascade","in":"query","required":false,"schema":{"type":"boolean","description":"When true, all URLs on this domain are deleted alongside the domain revoke. When false (default), URLs remain in the database but become unreachable (the domain stops resolving).","default":false,"title":"Cascade"},"description":"When true, all URLs on this domain are deleted alongside the domain revoke. When false (default), URLs remain in the database but become unreachable (the domain stops resolving)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDomainDeleteResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/custom-domains/{domain_id}/permanent":{"delete":{"tags":["Custom Domains"],"summary":"Remove Revoked Custom Domain","description":"Permanently delete a revoked custom domain to free the account slot.\n\nSoft-deleted (REVOKED) domains continue to occupy the caller's per-account\nquota so revoke is reversible and the audit trail stays intact. To free\nthe slot, the caller explicitly removes the doc via this endpoint. Only\nREVOKED docs are removable — call DELETE first to revoke an active one.\n\n**Authentication**: Required (JWT or API key with `domains:manage`).\n\n**Rate Limits**: 10/min.\n\n**Responses**:\n- 204 — removed\n- 403 — caller does not own this domain\n- 404 — domain not found (or invalid id)\n- 422 — domain isn't REVOKED","operationId":"removeCustomDomain","parameters":[{"name":"domain_id","in":"path","required":true,"schema":{"type":"string","description":"MongoDB ObjectId of the domain.","title":"Domain Id"},"description":"MongoDB ObjectId of the domain."}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/metadata":{"get":{"tags":["Metadata"],"summary":"Fetch Destination Meta Tags","description":"Fetch a destination page and return its existing meta tags.\n\nUse this to prefill ``meta_tags`` before customizing a link's social\npreview, or to check how a page will unfurl. Returns normalized\nbest-pick fields (og → twitter → html fallbacks) plus the raw\n``og``/``twitter`` tag families.\n\n**Authentication**: Optional. Authenticated callers get the higher\nper-account limit; anonymous calls are limited per IP. **API Key\nScope** (when authenticating): `urls:read`, `urls:manage`, or\n`admin:all`.\n\n**Rate Limits**: 60/min, 2,000/day authenticated; 15/min, 300/day\nanonymous — results are cached ~1h server-side, so repeat calls for\nthe same URL are cheap and don't refetch.","operationId":"getUrlMetadata","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","maxLength":2048,"description":"Destination https URL to fetch and parse.","examples":["https://example.com/article"],"title":"Url"},"description":"Destination https URL to fetch and parse."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{},{"ApiKeyAuth":[]},{"JWTAuth":[]}]}},"/api/v1/expand":{"get":{"tags":["Metadata"],"summary":"Expand a Short Link","description":"Follow a URL's redirect chain and return every hop in order.\n\nWorks on links from any shortener. Bodies are never fetched — only\neach hop's status and Location header — and results are cached ~1h\nserver-side, so repeat calls for the same URL don't refetch.\n\n**Authentication**: None required. Authenticated callers get the\nhigher per-account rate limit; anonymous calls are limited per IP.\n\n**Rate Limits**: 60/min, 2,000/day authenticated; 15/min, 300/day\nanonymous.","operationId":"expandUrl","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","maxLength":2048,"description":"Short or redirecting URL to follow, http or https.","examples":["https://spoo.me/example"],"title":"Url"},"description":"Short or redirecting URL to follow, http or https."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpandResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{},{"ApiKeyAuth":[]},{"JWTAuth":[]}]}},"/api/v1/domain-intel":{"get":{"tags":["Metadata"],"summary":"Domain Records","description":"DNS records, registration data, and TLS certificate of a host.\n\nRegistration comes from the registry's own RDAP server; ``age_days``\nis the strongest quick signal (freshly registered domains are the\nphishing tell). Results are cached ~24h server-side.\n\n**Authentication**: None required. Authenticated callers get the\nhigher per-account rate limit; anonymous calls are limited per IP.\n\n**Rate Limits**: 60/min, 2,000/day authenticated; 15/min, 300/day\nanonymous.","operationId":"getDomainIntel","parameters":[{"name":"host","in":"query","required":true,"schema":{"type":"string","maxLength":253,"description":"Hostname to look up (no scheme or path).","examples":["github.com"],"title":"Host"},"description":"Hostname to look up (no scheme or path)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainIntelResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{},{"ApiKeyAuth":[]},{"JWTAuth":[]}]}},"/api/v1/me":{"delete":{"tags":["Me"],"summary":"Delete Account","description":"Request permanent account deletion (GDPR Art. 17).\n\nRe-authentication is required: accounts with a password send\n``password``; OAuth-only accounts confirm by typing their exact\naccount email as ``confirm_email``. On success the account enters a\ngrace period (7 days by default) and `purge_after` marks its end —\nafter that instant a background sweep permanently erases the account,\nits links, and their analytics.\n\nDuring the grace period every login is blocked with error code\n``ACCOUNT_PENDING_DELETION``; ``POST /auth/restore`` cancels the\ndeletion and reactivates the account — with email + password, or with\nthe one-shot link mailed on this request (the OAuth-only path).\n\n**Authentication**: Required (JWT only — API keys and app tokens\ncannot delete the account)\n\n**Rate Limits**: 3/hour\n\n**Errors**: 403 when re-authentication fails (never says which field\nwas wrong), 409 when deletion is already pending.","operationId":"deleteMyAccount","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAccountRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeletionResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/features":{"get":{"tags":["Me"],"summary":"Get Feature Availability","description":"Return the availability state of every gated feature for this account.\n\nStates: `enabled` (render it), `hidden` (the feature doesn't exist for\nthis account), `locked` (reserved — render as upgrade-gated once plans\nship). Treat features missing from the map as `hidden`. Never used for\nenforcement — the write endpoints enforce the same gates server-side.\n\n**Authentication**: Required.","operationId":"getMyFeatures","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturesResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/me/layouts/{page}":{"get":{"tags":["Me"],"summary":"Get Page Layout","description":"Fetch the saved dashboard layout for a page.\n\nReturns `layout: null` when the user has never customized this page —\nclients render their built-in default in that case.\n\n**Authentication**: Required.","operationId":"getPageLayout","parameters":[{"name":"page","in":"path","required":true,"schema":{"enum":["analytics","overview"],"type":"string","description":"Layout slot, e.g. `analytics`","title":"Page"},"description":"Layout slot, e.g. `analytics`"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LayoutResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Me"],"summary":"Save Page Layout","description":"Save the layout document for a page.\n\nThe document is stored verbatim (last write wins) and echoed back.\nVersioning and validation are the client's responsibility; the body is\ncapped at 32 KiB.\n\n**Authentication**: Required.","operationId":"putPageLayout","parameters":[{"name":"page","in":"path","required":true,"schema":{"enum":["analytics","overview"],"type":"string","description":"Layout slot, e.g. `analytics`","title":"Page"},"description":"Layout slot, e.g. `analytics`"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutLayoutRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LayoutResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Me"],"summary":"Reset Page Layout","description":"Remove the saved layout so the page falls back to the client default.\n\nIdempotent: returns 204 whether or not an override existed.\n\n**Authentication**: Required.","operationId":"deletePageLayout","parameters":[{"name":"page","in":"path","required":true,"schema":{"enum":["analytics","overview"],"type":"string","description":"Layout slot, e.g. `analytics`","title":"Page"},"description":"Layout slot, e.g. `analytics`"}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/profile-pictures":{"get":{"tags":["Me"],"summary":"Get Available Profile Pictures","description":"List the profile pictures available to this account.\n\nOne entry per linked OAuth provider picture, with `is_current` marking\nthe active one.\n\n**Authentication**: Required.","operationId":"getMyProfilePictures","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailablePicturesResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Me"],"summary":"Set Profile Picture","description":"Set the profile picture to one of the available provider pictures.\n\n`picture_id` must be an id returned by the GET endpoint; unknown ids\nyield 404.\n\n**Authentication**: Required.","operationId":"setMyProfilePicture","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetProfilePictureRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilePictureMessageResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Me"],"summary":"Remove Profile Picture","description":"Unset the profile picture so the account falls back to the default.\n\nIdempotent: returns 200 whether or not a picture was set.\n\n**Authentication**: Required.","operationId":"deleteMyProfilePicture","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilePictureMessageResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/me/profile-pictures/upload":{"post":{"tags":["Me"],"summary":"Upload Profile Picture","description":"Upload a custom profile picture as a base64 data URI.\n\nAccepts image/png, image/jpeg and image/webp; size and content-type\nvalidation happens server-side against the configured upload cap.\n\n**Authentication**: Required.","operationId":"uploadMyProfilePicture","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadProfilePictureRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilePictureMessageResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/preview/{short_code}":{"get":{"tags":["Public"],"summary":"Public Link Preview","description":"Preview where a short link leads before following it.\n\nReturns the link's resolved facts — status, creation date, whether a\npassword gates it, and (only while the link is active and unlocked)\nthe destination plus every geo-targeted destination, grouped by URL.\n\n**Authentication**: None. The preview shows the same resolved facts to\neveryone; owner-set social meta never appears here.\n\n**Rate Limits**: 30/min, 2,000/day.","operationId":"getPublicPreview","parameters":[{"name":"short_code","in":"path","required":true,"schema":{"type":"string","title":"Short Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPreviewResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/api/v1/reports":{"post":{"tags":["Reports & Contact"],"summary":"Report URLs","description":"Report shortened URLs for abuse — one or many per request.\n\nAccepts bare codes or full short URLs (custom domains included) and\nreturns a per-item accepted/rejected breakdown — bad codes don't sink\nthe batch. Re-reports of a code increment its counter rather than\nfiling duplicates.\n\n**Authentication**: Optional. Anonymous submissions are captcha-gated\nand capped at **25 items/request**; authenticated callers (session or\nAPI key) skip the captcha and may send **100 items/request**.\n\n**API Key Scope**: `reports:create` or `admin:all`\n\n**Rate Limits** (per submission, not per item):\n\n- Authenticated: 30/min, 500/day\n- Anonymous: 5/min, 40/day","operationId":"submitReports","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReportsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportSubmissionResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Not configured — the required webhook is unset on this instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{},{"ApiKeyAuth":[]},{"JWTAuth":[]}]}},"/api/v1/contact":{"post":{"tags":["Reports & Contact"],"summary":"Contact","description":"Send a message to the site operators.\n\nJSON twin of the ``/contact`` form — same service, same webhook, same\nbudget values.\n\n**Authentication**: None.\n\n**Rate Limits**: 5/min, 20/hour, 50/day","operationId":"submitContactMessage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactOkResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Not configured — the required webhook is unset on this instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/api/v1/webhooks/event-types":{"get":{"tags":["Webhooks"],"summary":"List Webhook Event Types","description":"The public webhook event catalog — documentation as API.\n\nEvery subscribable event type with its category, firing frequency, and\nan exact sample payload (the same fixture test sends deliver).\n\n**Authentication**: None.","operationId":"listWebhookEventTypes","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventTypesResponse"}}}}}}},"/api/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"List Webhook Endpoints","description":"List all webhook endpoints on the account (secrets never included).","operationId":"listWebhookEndpoints","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointsListResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Webhooks"],"summary":"Create Webhook Endpoint","description":"Register an HTTPS endpoint to receive event deliveries.\n\nThe `signing_secret` is returned **only in this response** — store it;\nit is what your server uses to verify `webhook-signature` headers\n(Standard Webhooks, HMAC-SHA256).\n\n**Authentication**: Required (verified email). Feature-flagged.\n\n**Rate Limits**: 10/hour","operationId":"createWebhookEndpoint","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreatedResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/webhooks/{endpoint_id}":{"get":{"tags":["Webhooks"],"summary":"Get Webhook Endpoint","operationId":"getWebhookEndpoint","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Webhooks"],"summary":"Update Webhook Endpoint","description":"Update url, events, scope, flavor, description, or pause/resume.\n\nA new `url` is re-checked (https + public address) before it takes\neffect. `status` accepts `active`/`paused`; `disabled` is system-set —\nre-activating a disabled endpoint clears its failure bookkeeping.","operationId":"updateWebhookEndpoint","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookEndpointRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete Webhook Endpoint","operationId":"deleteWebhookEndpoint","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/webhooks/{endpoint_id}/secret":{"get":{"tags":["Webhooks"],"summary":"Reveal Signing Secret","description":"The full signing secret, for the endpoint owner. Secrets are stored\nencrypted and readable on demand; treat the response like a password.\n\n**Authentication**: Interactive session only — API keys are refused,\nlike every operation that exposes or mints credential material.","operationId":"revealWebhookSecret","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecretResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/webhooks/{endpoint_id}/test":{"post":{"tags":["Webhooks"],"summary":"Send Test Event","description":"Send a sample of any catalog event through the real pipeline —\nrendered in the endpoint's flavor, signed with its real secret — and\nreturn the delivery outcome synchronously.","operationId":"testWebhookEndpoint","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestWebhookRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/webhooks/{endpoint_id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List Webhook Deliveries","description":"The delivery log: what was sent, when, each attempt's outcome, and\nthe exact rendered body (30-day retention).","operationId":"listWebhookDeliveries","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Page Size"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/DeliveryStatus"},{"type":"null"}],"title":"Status"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveriesListResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/webhooks/{endpoint_id}/deliveries/{delivery_id}/retry":{"post":{"tags":["Webhooks"],"summary":"Retry Delivery","description":"Redeliver a completed delivery: same `webhook-id`, same body, fresh\nattempt — consumers dedup on `webhook-id`.","operationId":"retryWebhookDelivery","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}},{"name":"delivery_id","in":"path","required":true,"schema":{"type":"string","title":"Delivery Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryResponse"}}}},"400":{"description":"Bad Request — invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient permissions or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AbVariantRequest":{"properties":{"url":{"type":"string","maxLength":8192,"minLength":1,"title":"Url","description":"Destination URL for this variant.","examples":["https://example.com/b"]},"weight":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Weight","description":"Percentage of visitors sent to this variant (1-100).","examples":[40]}},"type":"object","required":["url","weight"],"title":"AbVariantRequest","description":"One A/B split destination as sent on create/update."},"AbVariantResponse":{"properties":{"url":{"type":"string","title":"Url","description":"Variant destination URL."},"weight":{"type":"integer","title":"Weight","description":"Percentage of visitors sent here."}},"type":"object","required":["url","weight"],"title":"AbVariantResponse","description":"One A/B split destination."},"AccountDeletionResponse":{"properties":{"purge_after":{"type":"string","title":"Purge After","description":"When the grace period ends and the erasure sweep may pick the account up. Restoring before this instant cancels the deletion.","examples":["2026-08-26T00:00:00+00:00"]}},"type":"object","required":["purge_after"],"title":"AccountDeletionResponse","description":"Deletion accepted — the account is now pending erasure."},"AliasCheckResponse":{"properties":{"available":{"type":"boolean","title":"Available","description":"Whether the alias is free to use."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"When unavailable: 'length', 'format', 'reserved', 'taken', or 'emoji_policy' (emoji alias contains sequences outside the accepted set — ZWJ, flags, keycaps, or too-new emoji).","examples":["taken"]}},"type":"object","required":["available"],"title":"AliasCheckResponse","description":"Response body for GET /api/v1/shorten/check-alias.\n\n``available`` is true only when the alias passes format/length validation\nAND is not already taken. When false, ``reason`` explains why so the UI\ncan render a precise, non-generic message."},"ApiKeyActionResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the action completed successfully"},"action":{"type":"string","title":"Action","description":"Action that was performed","examples":["deleted"]}},"type":"object","required":["success","action"],"title":"ApiKeyActionResponse","description":"Response body for DELETE /api/v1/keys/{key_id}."},"ApiKeyCreatedResponse":{"properties":{"id":{"type":"string","title":"Id","description":"API key ID","examples":["507f1f77bcf86cd799439011"]},"name":{"type":"string","title":"Name","description":"Human-readable key name","examples":["My Production Key"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description","examples":["Used by the mobile app"]},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"Permission scopes granted to this key","examples":[["shorten:create","stats:read"]]},"created_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Created At","description":"Creation time as Unix timestamp","examples":[1704067200]},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires At","description":"Expiration time as Unix timestamp, or null if no expiration","examples":[1735689600]},"revoked":{"type":"boolean","title":"Revoked","description":"Whether the key has been revoked"},"token_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Prefix","description":"First characters of the token for identification","examples":["spoo_abc1"]},"last_used_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Used At","description":"Last time this key authenticated a request, as Unix timestamp. Null if the key has never been used. Updated at most once per hour.","examples":[1704067200]},"token":{"type":"string","title":"Token","description":"Full API key token (only returned once at creation time)","examples":["spoo_abc123def456ghi789"]}},"type":"object","required":["id","name","scopes","revoked","token"],"title":"ApiKeyCreatedResponse","description":"Response for POST /api/v1/keys (201).\n\nExtends ApiKeyResponse by adding the full ``token``.  This is the ONLY time\nthe token is returned — it is hashed before storage."},"ApiKeyResponse":{"properties":{"id":{"type":"string","title":"Id","description":"API key ID","examples":["507f1f77bcf86cd799439011"]},"name":{"type":"string","title":"Name","description":"Human-readable key name","examples":["My Production Key"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description","examples":["Used by the mobile app"]},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"Permission scopes granted to this key","examples":[["shorten:create","stats:read"]]},"created_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Created At","description":"Creation time as Unix timestamp","examples":[1704067200]},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires At","description":"Expiration time as Unix timestamp, or null if no expiration","examples":[1735689600]},"revoked":{"type":"boolean","title":"Revoked","description":"Whether the key has been revoked"},"token_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Prefix","description":"First characters of the token for identification","examples":["spoo_abc1"]},"last_used_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Used At","description":"Last time this key authenticated a request, as Unix timestamp. Null if the key has never been used. Updated at most once per hour.","examples":[1704067200]}},"type":"object","required":["id","name","scopes","revoked"],"title":"ApiKeyResponse","description":"A single API key entry as returned by the list endpoint.\n\nThe full token is never returned here — only the ``token_prefix`` for display."},"ApiKeysListResponse":{"properties":{"keys":{"items":{"$ref":"#/components/schemas/ApiKeyResponse"},"type":"array","title":"Keys","description":"List of API keys for the authenticated user"}},"type":"object","required":["keys"],"title":"ApiKeysListResponse","description":"Response body for GET /api/v1/keys."},"AppGrantResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Grant ID (accepted as `grant_id` by POST /auth/device/revoke)","examples":["665f1c2ab7e94d0c8a1f2b3c"]},"app":{"type":"string","title":"App","description":"App registry key (config/apps.yaml). Shares a namespace with the frontend catalogue slugs and is the `app_id` handle for POST /auth/device/revoke.","examples":["spoo-cli"]},"app_name":{"type":"string","title":"App Name","description":"Display name from the registry (falls back to `app`)","examples":["Spoo CLI"]},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon","description":"Registry icon filename, or null when the entry is gone","examples":["spoo-cli.svg"]},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"Effective scope slugs the grant confers. Empty list means a legacy unrestricted grant (consented before scoped grants existed) — full account access, not zero access.","examples":[["shorten:create","urls:read"]]},"permissions":{"items":{"type":"string"},"type":"array","title":"Permissions","description":"Human-readable consent sentences derived from `scopes` (full-access sentence for legacy unrestricted grants)","examples":[["Create short links","List and read links"]]},"granted_at":{"type":"string","title":"Granted At","description":"When access was granted (ISO 8601 UTC)"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At","description":"Last token exchange/refresh by this app, null if never used"}},"type":"object","required":["id","app","app_name","scopes","permissions","granted_at"],"title":"AppGrantResponse","description":"A single connected app as returned by the list endpoint."},"AppGrantsListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AppGrantResponse"},"type":"array","title":"Items","description":"Active grants, newest granted_at first"}},"type":"object","required":["items"],"title":"AppGrantsListResponse","description":"Response body for GET /api/v1/apps."},"AuthProviderInfo":{"properties":{"provider":{"anyOf":[{"$ref":"#/components/schemas/OAuthProvider"},{"type":"null"}],"description":"OAuth provider name","examples":["google"]},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Email address from the OAuth provider","examples":["user@gmail.com"]},"linked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linked At","description":"When the provider was linked","examples":["2025-01-15T10:30:00+00:00"]}},"type":"object","title":"AuthProviderInfo","description":"Minimal OAuth provider entry returned inside UserProfileResponse."},"AvailablePicture":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier (provider_providerUserId)"},"url":{"type":"string","title":"Url","description":"Picture URL"},"source":{"$ref":"#/components/schemas/OAuthProvider","description":"OAuth provider source"},"is_current":{"type":"boolean","title":"Is Current","description":"Whether this is the active picture"}},"type":"object","required":["id","url","source","is_current"],"title":"AvailablePicture","description":"A profile picture option from a linked OAuth provider."},"AvailablePicturesResponse":{"properties":{"pictures":{"items":{"$ref":"#/components/schemas/AvailablePicture"},"type":"array","title":"Pictures"}},"type":"object","required":["pictures"],"title":"AvailablePicturesResponse"},"BulkDeleteUrlsRequest":{"properties":{"ids":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Ids","description":"URL ids (MongoDB ObjectIds, as returned by the list endpoint). 1 to 100 per request; duplicates are deduplicated server-side (first occurrence wins). One malformed id rejects the whole request — nothing is attempted.","examples":[["665f0c2f9e7a4b1d2c3d4e5f","665f0c2f9e7a4b1d2c3d4e60"]]}},"type":"object","required":["ids"],"title":"BulkDeleteUrlsRequest","description":"Request body for bulk delete — ids only, no parameters."},"BulkDeleteUrlsResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Confirmation message.","examples":["deleted 42 URLs on links.acme.com"]},"count":{"type":"integer","title":"Count","description":"Number of URLs deleted.","examples":[42]},"domain":{"type":"string","title":"Domain","description":"Domain whose URLs were deleted.","examples":["links.acme.com"]}},"type":"object","required":["message","count","domain"],"title":"BulkDeleteUrlsResponse","description":"Response body for DELETE /api/v1/urls?domain=<fqdn> (bulk delete)."},"BulkMoveDomainRequest":{"properties":{"ids":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Ids","description":"URL ids (MongoDB ObjectIds, as returned by the list endpoint). 1 to 100 per request; duplicates are deduplicated server-side (first occurrence wins). One malformed id rejects the whole request — nothing is attempted.","examples":[["665f0c2f9e7a4b1d2c3d4e5f","665f0c2f9e7a4b1d2c3d4e60"]]},"domain":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"title":"Domain","description":"Target domain for every id — a custom domain you own (must be ACTIVE), or `null` to move back to the system default. One target for the whole batch.","examples":["links.acme.com"]}},"type":"object","required":["ids","domain"],"title":"BulkMoveDomainRequest","description":"Request body for bulk domain move."},"BulkOperationSummary":{"properties":{"total":{"type":"integer","title":"Total","description":"Unique ids in the request (after dedupe)."},"succeeded":{"type":"integer","title":"Succeeded","description":"Rows with ok=true."},"failed":{"type":"integer","title":"Failed","description":"Rows with ok=false."}},"type":"object","required":["total","succeeded","failed"],"title":"BulkOperationSummary","description":"Counts derived from the result rows."},"BulkTagUrlsRequest":{"properties":{"ids":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Ids","description":"URL ids (MongoDB ObjectIds, as returned by the list endpoint). 1 to 100 per request; duplicates are deduplicated server-side (first occurrence wins). One malformed id rejects the whole request — nothing is attempted.","examples":[["665f0c2f9e7a4b1d2c3d4e5f","665f0c2f9e7a4b1d2c3d4e60"]]},"add":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Add","description":"Tag ids to add to every id (at most 10); every one must be a tag you own. Tags a link already carries are kept once.","examples":[["665f0c2f9e7a4b1d2c3d4e5f"]]},"remove":{"items":{"type":"string"},"type":"array","title":"Remove","description":"Tag ids to remove from every id. Tags a link does not carry are ignored.","examples":[["665f0c2f9e7a4b1d2c3d4e60"]]}},"type":"object","required":["ids"],"title":"BulkTagUrlsRequest","description":"Request body for bulk tag / untag, by tag id.\n\nAt least one of ``add`` or ``remove`` must name a tag, and no tag may be\nin both."},"BulkUpdateExpiryRequest":{"properties":{"ids":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Ids","description":"URL ids (MongoDB ObjectIds, as returned by the list endpoint). 1 to 100 per request; duplicates are deduplicated server-side (first occurrence wins). One malformed id rejects the whole request — nothing is attempted.","examples":[["665f0c2f9e7a4b1d2c3d4e5f","665f0c2f9e7a4b1d2c3d4e60"]]},"expire_after":{"anyOf":[{"type":"string","format":"date-time"},{"type":"integer"},{"type":"null"}],"title":"Expire After","description":"Expiration applied to every id — ISO 8601 or epoch seconds, must be in the future. Pass `null` to clear expiry. One value for the whole batch.","examples":[1767225600]}},"type":"object","required":["ids","expire_after"],"title":"BulkUpdateExpiryRequest","description":"Request body for bulk set/clear expiry."},"BulkUpdateStatusRequest":{"properties":{"ids":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Ids","description":"URL ids (MongoDB ObjectIds, as returned by the list endpoint). 1 to 100 per request; duplicates are deduplicated server-side (first occurrence wins). One malformed id rejects the whole request — nothing is attempted.","examples":[["665f0c2f9e7a4b1d2c3d4e5f","665f0c2f9e7a4b1d2c3d4e60"]]},"status":{"type":"string","enum":["ACTIVE","INACTIVE"],"title":"Status","description":"Status applied to every id. `ACTIVE` enables redirects, `INACTIVE` disables them. `BLOCKED`/`EXPIRED` are not caller-settable, same as the single-item status endpoint.","examples":["INACTIVE"]}},"type":"object","required":["ids","status"],"title":"BulkUpdateStatusRequest","description":"Request body for bulk activate/deactivate."},"BulkUrlOperationResponse":{"properties":{"summary":{"$ref":"#/components/schemas/BulkOperationSummary"},"results":{"items":{"$ref":"#/components/schemas/BulkUrlResultRow"},"type":"array","title":"Results","description":"One row per unique requested id, in request order."}},"type":"object","required":["summary","results"],"title":"BulkUrlOperationResponse","description":"Envelope for every bulk URL operation."},"BulkUrlResultRow":{"properties":{"id":{"type":"string","title":"Id","description":"The requested URL id."},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alias","description":"Echoed when the id resolved to a URL you own; null otherwise."},"ok":{"type":"boolean","title":"Ok","description":"Whether the operation succeeded for this id."},"error_code":{"anyOf":[{"type":"string","enum":["not_found","forbidden","conflict","validation_error","internal","not_attempted"]},{"type":"null"}],"title":"Error Code","description":"Machine-readable failure cause; null when ok."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Human-readable failure message; null when ok."}},"type":"object","required":["id","ok"],"title":"BulkUrlResultRow","description":"Per-item verdict.\n\n``error_code`` reuses the API's error-code slugs so clients share\none mapping with the single-item routes: ``not_found`` (no such URL\nin your account — someone else's id answers the same, deliberately),\n``forbidden`` (blocked link), ``conflict``, ``validation_error``,\nplus ``internal`` (unexpected per-item failure, logged server-side)\nand ``not_attempted`` (processing aborted before this item).\n``error`` is display-safe but not stable; ``error_code`` is the key\nto branch on."},"ChainHop":{"properties":{"url":{"type":"string","title":"Url"},"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status","description":"HTTP status; null when the hop never answered."},"https":{"type":"boolean","title":"Https"}},"type":"object","required":["url","https"],"title":"ChainHop"},"ClaimItemRequest":{"properties":{"url_id":{"type":"string","maxLength":24,"minLength":24,"pattern":"^[0-9a-f]{24}$","title":"Url Id","description":"ObjectId of the URL to claim (from the shorten response).","examples":["507f1f77bcf86cd799439011"]},"token":{"type":"string","maxLength":256,"minLength":43,"title":"Token","description":"The one-time claim_token returned by the anonymous shorten call — the bearer proof of creation."}},"type":"object","required":["url_id","token"],"title":"ClaimItemRequest","description":"One (url_id, token) pair in a claim batch."},"ClaimResultItem":{"properties":{"url_id":{"type":"string","title":"Url Id","description":"The url_id from the request item."},"status":{"type":"string","enum":["claimed","already_yours","invalid"],"title":"Status","description":"`claimed` — ownership transferred and the token burned; `already_yours` — you already own this URL (idempotent repeat); `invalid` — unknown id, wrong token, or a link that is not claimable (deliberately indistinguishable)."}},"type":"object","required":["url_id","status"],"title":"ClaimResultItem","description":"Per-item outcome of a claim batch."},"ClaimUrlsRequest":{"properties":{"claims":{"items":{"$ref":"#/components/schemas/ClaimItemRequest"},"type":"array","maxItems":16,"minItems":1,"title":"Claims","description":"URLs to claim. Each item resolves independently."}},"type":"object","required":["claims"],"title":"ClaimUrlsRequest","description":"Request body for POST /api/v1/urls/claim (bulk-first, like reports)."},"ClaimUrlsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ClaimResultItem"},"type":"array","title":"Results","description":"One outcome per submitted item, in request order."},"claimed":{"type":"integer","title":"Claimed","description":"Convenience count of `claimed` results."}},"type":"object","required":["results","claimed"],"title":"ClaimUrlsResponse","description":"Response body for POST /api/v1/urls/claim.\n\nThe batch never hard-fails: every submitted item gets a result, in\nrequest order."},"ComputedMetrics":{"properties":{"unique_click_rate":{"type":"number","title":"Unique Click Rate"},"repeat_click_rate":{"type":"number","title":"Repeat Click Rate"},"average_clicks_per_visitor":{"type":"number","title":"Average Clicks Per Visitor"}},"type":"object","required":["unique_click_rate","repeat_click_rate","average_clicks_per_visitor"],"title":"ComputedMetrics","description":"Optional computed metrics added by format_stats_response_with_metadata."},"ContactOkResponse":{"properties":{"ok":{"type":"boolean","title":"Ok","default":true}},"type":"object","title":"ContactOkResponse","description":"Response body for POST /api/v1/contact."},"ContactRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Sender's email address"},"message":{"type":"string","maxLength":4000,"minLength":1,"title":"Message","description":"Message body (1-4000 characters)"},"captcha_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Captcha Token","description":"hCaptcha response token — required when captcha is configured"}},"type":"object","required":["email","message"],"title":"ContactRequest","description":"Request body for POST /api/v1/contact."},"CreateApiKeyRequest":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name","description":"Human-readable key name","examples":["My Production Key"]},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Optional description of what this key is used for","examples":["Used by the mobile app for URL shortening"]},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"Permission scopes for the key","examples":[["shorten:create","stats:read"]]},"expires_at":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"null"}],"title":"Expires At","description":"Expiration time. ISO 8601 string (e.g. `2026-01-01T00:00:00Z`) or Unix epoch seconds (e.g. `1735689599`). Omit for non-expiring key.","examples":["2026-01-01T00:00:00Z",1735689599]}},"type":"object","required":["name","scopes"],"title":"CreateApiKeyRequest","description":"Request body for POST /api/v1/keys."},"CreateCustomDomainRequest":{"properties":{"fqdn":{"type":"string","maxLength":253,"title":"Fqdn","description":"The fully-qualified domain to register (e.g. links.acme.com).","examples":["links.acme.com"]}},"type":"object","required":["fqdn"],"title":"CreateCustomDomainRequest","description":"Body for ``POST /api/v1/custom-domains``."},"CreateReportsRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ReportItemRequest"},"type":"array","title":"Items","description":"Reported links — anonymous ≤ 25 per request, authenticated ≤ 100"},"reporter_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Reporter Email","description":"Optional contact for resolution follow-up"},"reporter_org":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Reporter Org","description":"Optional organisation name"},"captcha_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Captcha Token","description":"hCaptcha response token — required for anonymous submissions when captcha is configured; ignored for authenticated callers"}},"type":"object","required":["items"],"title":"CreateReportsRequest","description":"Request body for POST /api/v1/reports.\n\n``items`` size is validated in the service (anonymous ≤ 25,\nauthenticated ≤ 100; empty → 400) because the cap depends on the\ncaller's auth state."},"CreateTagRequest":{"properties":{"name":{"type":"string","maxLength":64,"title":"Name","description":"Tag name, at most 32 characters. Lowercased and trimmed on write; letters, digits, spaces, `-`, `_` and `.` only. Unique per account.","examples":["launch"]},"color":{"anyOf":[{"$ref":"#/components/schemas/TagColor"},{"type":"null"}],"description":"One of the palette keys. Omit on create to get the least-used colour in your account.","examples":["violet"]},"icon":{"$ref":"#/components/schemas/TagIcon","description":"Icon key from the curated set (lucide names). Defaults to `tag`.","default":"tag","examples":["rocket"]}},"type":"object","required":["name"],"title":"CreateTagRequest"},"CreateUrlRequest":{"properties":{"long_url":{"type":"string","maxLength":8192,"title":"Long Url","description":"The destination URL to shorten. Must be a valid http:// or https:// URL.","examples":["https://example.com/very/long/url/path"]},"alias":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Alias","description":"Custom short code. Either alphanumeric (a-z, A-Z, 0-9, `_`, `-`; 3-16 chars) or emoji-only (1-15 fully-qualified emoji — no ZWJ sequences, flags, or keycaps). Auto-generated if omitted.","examples":["mylink","🚀🔥"]},"alias_type":{"type":"string","enum":["alphanumeric","emoji"],"title":"Alias Type","description":"Alias style to auto-generate when `alias` is omitted. Ignored when `alias` is provided.","default":"alphanumeric"},"password":{"anyOf":[{"type":"string","maxLength":128,"minLength":8},{"type":"null"}],"title":"Password","description":"Password to protect the URL. Min 8 chars, must contain letter + number + special char.","examples":["secure@123"]},"block_bots":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Block Bots","description":"Block known bot user agents from accessing the URL."},"max_clicks":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Max Clicks","description":"Maximum clicks before the URL expires. Must be positive.","examples":[100]},"expire_after":{"anyOf":[{"type":"string","format":"date-time"},{"type":"integer"},{"type":"null"}],"title":"Expire After","description":"Expiration time. ISO 8601 string (e.g. `2025-12-31T23:59:59Z`) or Unix epoch seconds (e.g. `1735689599`).","examples":["2025-12-31T23:59:59Z",1735689599]},"starts_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"integer"},{"type":"null"}],"title":"Starts At","description":"Go-live time. The link is not live before this moment. ISO 8601 string or Unix epoch seconds; must be in the future and before `expire_after`. Requires authentication.","examples":["2026-09-10T18:00:00+05:30",1789500000]},"pre_start_url":{"anyOf":[{"type":"string","maxLength":8192},{"type":"null"}],"title":"Pre Start Url","description":"Where visitors are sent before `starts_at`. Omit for the not-yet-live page. No effect without `starts_at`.","examples":["https://example.com/coming-soon"]},"private_stats":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Private Stats","description":"Make statistics private (only owner can view). Requires authentication."},"domain":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"title":"Domain","description":"Custom domain fqdn to scope the short link under (e.g. `links.acme.com`). Requires authentication and ownership of an ACTIVE custom domain. Omit for the default spoo.me namespace.","examples":["links.acme.com"]},"geo_rules":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Geo Rules","description":"Per-country destination overrides: ISO 3166-1 alpha-2 country code → destination URL (at most 50 entries by default). Visitors from a listed country are redirected to that URL; everyone else gets the default destination (`url`). Requires authentication.","examples":[{"IN":"https://example.in/","US":"https://example.com/us"}]},"expired_redirect_url":{"anyOf":[{"type":"string","maxLength":8192},{"type":"null"}],"title":"Expired Redirect Url","description":"Where visitors land once the link has expired, by time or by click limit, instead of the expired page. Validated like a destination. Requires authentication.","examples":["https://example.com/offer-ended"]},"tag_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tag Ids","description":"Ids of tags from `GET /api/v1/tags`, at most 10 per link. Every id must be one of your tags (400 otherwise). On PATCH the list replaces the stored one; `null` or `[]` clears it.","examples":[["665f0c2f9e7a4b1d2c3d4e5f"]]},"ab_variants":{"anyOf":[{"items":{"$ref":"#/components/schemas/AbVariantRequest"},"type":"array"},{"type":"null"}],"title":"Ab Variants","description":"Weighted split destinations: each entry is `{url, weight}` where `weight` is the percentage of visitors sent there (integers, summing to at most 100). The default destination (`url`) receives the remainder. Requires authentication.","examples":[[{"url":"https://example.com/b","weight":40}]]},"meta_tags":{"anyOf":[{"$ref":"#/components/schemas/MetaTagsRequest"},{"type":"null"}],"description":"Custom social preview served to link-preview crawlers (WhatsApp, Discord, Slack, iMessage, …). The object replaces the whole setting; on PATCH pass null to remove. Requires a verified account with the feature enabled. Note: platforms cache previews for ~7-30 days — edits propagate slowly (the Facebook Sharing Debugger, LinkedIn Post Inspector, and Telegram's @WebpageBot force a refresh)."}},"type":"object","required":["long_url"],"title":"CreateUrlRequest","description":"Request body for creating a new shortened URL.\n\nAccepts ``url`` as an alias for ``long_url`` — the existing API supports both."},"CreateWebhookEndpointRequest":{"properties":{"url":{"type":"string","maxLength":2048,"title":"Url","description":"HTTPS URL that receives event deliveries.","examples":["https://example.com/hooks/spoo"]},"events":{"items":{"type":"string"},"type":"array","maxItems":32,"minItems":1,"title":"Events","description":"Event types or patterns to subscribe to. Supports `link.*`-style category wildcards and `*` for everything.","examples":[["link.clicked","link.expired"]]},"description":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Description"},"scope_links":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":256},{"type":"null"}],"title":"Scope Links","description":"Link IDs to scope deliveries to. Omit (or null) for all links, including ones created later."},"flavor":{"$ref":"#/components/schemas/WebhookFlavor","description":"Payload presentation. `raw` is the documented contract.","default":"raw"}},"type":"object","required":["url","events"],"title":"CreateWebhookEndpointRequest"},"CustomDomainDeleteResponse":{"properties":{"id":{"type":"string","title":"Id","description":"ID of the revoked domain."},"fqdn":{"type":"string","title":"Fqdn","description":"The revoked fqdn."},"cascade":{"type":"boolean","title":"Cascade","description":"Whether URLs on the domain were also deleted."},"urls_deleted":{"type":"integer","title":"Urls Deleted","description":"URL count deleted by cascade (0 when cascade=false)."}},"type":"object","required":["id","fqdn","cascade","urls_deleted"],"title":"CustomDomainDeleteResponse","description":"Response for domain revoke. ``urls_deleted`` is 0 unless cascade was true."},"CustomDomainListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CustomDomainResponse"},"type":"array","title":"Items"},"page":{"type":"integer","title":"Page"},"pageSize":{"type":"integer","title":"Pagesize"},"total":{"type":"integer","title":"Total"},"hasNext":{"type":"boolean","title":"Hasnext"}},"type":"object","required":["items","page","pageSize","total","hasNext"],"title":"CustomDomainListResponse","description":"Paginated list of the caller's custom domains."},"CustomDomainResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Server-generated domain ID."},"fqdn":{"type":"string","title":"Fqdn","description":"Canonical fqdn (lowercased, trailing dot stripped)."},"status":{"$ref":"#/components/schemas/DomainStatus"},"verification_method":{"$ref":"#/components/schemas/VerificationMethod"},"dns_records":{"items":{"$ref":"#/components/schemas/DnsRecord"},"type":"array","title":"Dns Records","description":"DNS records the user must publish at their DNS provider."},"setup_notes":{"items":{"type":"string"},"type":"array","title":"Setup Notes","description":"Human-readable setup warnings/instructions specific to this domain."},"created_at":{"type":"string","title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"last_verified_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Verified At"},"last_verification_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Verification Error"},"root_redirect":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Root Redirect","description":"Destination for `GET /` on this domain. Honored only when status=ACTIVE."},"not_found_redirect":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Not Found Redirect","description":"Fallback for non-alias paths. Honored only when status=ACTIVE."},"custom_robots_txt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Robots Txt","description":"Override body served at /robots.txt. Honored only when status=ACTIVE."}},"type":"object","required":["id","fqdn","status","verification_method","created_at"],"title":"CustomDomainResponse","description":"A single custom domain — covers create, get, verify, and list responses."},"DeleteAccountRequest":{"properties":{"password":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Password","description":"Account password — re-auth for accounts with a password set","examples":["MySecurePass123!"]},"confirm_email":{"anyOf":[{"type":"string","maxLength":320},{"type":"null"}],"title":"Confirm Email","description":"The exact account email, typed to confirm — re-auth for OAuth-only accounts (no password set)","examples":["user@example.com"]}},"type":"object","title":"DeleteAccountRequest","description":"Request body for DELETE /api/v1/me.\n\nExactly one re-auth proof applies per account: ``password`` for\naccounts with a password set, ``confirm_email`` (the exact account\nemail, typed) for OAuth-only accounts. The wrong proof — or a missing\none — fails re-authentication; the response never says which."},"DeleteUrlResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Confirmation message.","examples":["URL deleted"]},"id":{"type":"string","title":"Id","description":"ID of the deleted URL.","examples":["507f1f77bcf86cd799439011"]}},"type":"object","required":["message","id"],"title":"DeleteUrlResponse","description":"Response body for DELETE /api/v1/urls/{url_id}."},"DeliveriesListResponse":{"properties":{"deliveries":{"items":{"$ref":"#/components/schemas/WebhookDeliveryResponse"},"type":"array","title":"Deliveries"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"}},"type":"object","required":["deliveries","total","page","page_size"],"title":"DeliveriesListResponse"},"DeliveryAttemptResponse":{"properties":{"attempted_at":{"type":"integer","title":"Attempted At"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Ms"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"response_body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Body"}},"type":"object","required":["attempted_at"],"title":"DeliveryAttemptResponse"},"DeliveryStatus":{"type":"string","enum":["pending","success","failed"],"title":"DeliveryStatus"},"DeviceRefreshRequest":{"properties":{"refresh_token":{"type":"string","minLength":1,"title":"Refresh Token","description":"JWT refresh token issued by /auth/device/token"}},"type":"object","required":["refresh_token"],"title":"DeviceRefreshRequest","description":"Request body for POST /auth/device/refresh."},"DeviceRefreshResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"New JWT access token"},"refresh_token":{"type":"string","title":"Refresh Token","description":"New JWT refresh token"}},"type":"object","required":["access_token","refresh_token"],"title":"DeviceRefreshResponse","description":"Response body for POST /auth/device/refresh (200)."},"DeviceTokenRequest":{"properties":{"code":{"type":"string","maxLength":128,"minLength":1,"title":"Code","description":"One-time auth code from the device callback page"},"code_verifier":{"type":"string","maxLength":128,"minLength":43,"pattern":"^[A-Za-z0-9\\-._~]+$","title":"Code Verifier","description":"PKCE code verifier (RFC 7636). Must hash (S256) to the code_challenge sent at /auth/device/login."}},"type":"object","required":["code","code_verifier"],"title":"DeviceTokenRequest","description":"Request body for POST /auth/device/token."},"DeviceTokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"JWT access token"},"refresh_token":{"type":"string","title":"Refresh Token","description":"JWT refresh token"},"user":{"$ref":"#/components/schemas/UserProfileResponse","description":"User profile"}},"type":"object","required":["access_token","refresh_token","user"],"title":"DeviceTokenResponse","description":"Response body for POST /auth/device/token (200)."},"DnsRecord":{"properties":{"type":{"type":"string","enum":["CNAME","TXT","A"],"title":"Type","description":"Record type."},"name":{"type":"string","title":"Name","description":"Record name (subdomain or @ for apex)."},"value":{"type":"string","title":"Value","description":"Record value."},"purpose":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purpose","description":"Human-readable note explaining why this record is needed."}},"type":"object","required":["type","name","value"],"title":"DnsRecord","description":"One DNS record the user must publish to complete setup."},"DomainIntelResponse":{"properties":{"host":{"type":"string","title":"Host"},"registrable_domain":{"type":"string","title":"Registrable Domain"},"dns":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object","title":"Dns"},"whois":{"anyOf":[{"$ref":"#/components/schemas/DomainWhois"},{"type":"null"}]},"ssl":{"anyOf":[{"$ref":"#/components/schemas/DomainSsl"},{"type":"null"}]},"fetched_at":{"type":"string","format":"date-time","title":"Fetched At"}},"type":"object","required":["host","registrable_domain","dns","fetched_at"],"title":"DomainIntelResponse","description":"Public records of a destination host: DNS, RDAP registration, TLS.\n\n``whois``/``ssl`` are null when the registry or handshake doesn't\nanswer — absence of data, never a verdict."},"DomainSsl":{"properties":{"issuer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer"},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject"},"valid_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valid From"},"valid_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valid To"},"days_left":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Days Left"},"sans":{"items":{"type":"string"},"type":"array","title":"Sans"}},"type":"object","title":"DomainSsl"},"DomainStatus":{"type":"string","enum":["pending","verifying","active","suspended","revoked"],"title":"DomainStatus","description":"Lifecycle state of a custom domain registration."},"DomainWhois":{"properties":{"registrar":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registrar"},"created":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created"},"updated":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated"},"expires":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires"},"age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Age Days","description":"Days since registration; young = suspect."}},"type":"object","title":"DomainWhois"},"EmojiEntry":{"properties":{"c":{"type":"string","title":"C","description":"Raw canonical emoji character (no U+FE0F variation selector), matching how aliases are stored and echoed."},"n":{"type":"string","title":"N","description":"Human-readable name, lowercased with spaces (e.g. \"rocket\"). The primary search key."},"g":{"type":"string","title":"G","description":"Canonical Unicode category display name (e.g. \"Smileys & Emotion\"), for the picker's category tabs. Entries in the array are already sorted by canonical group and within-group order, so a picker opens on Smileys rather than symbols."},"gen":{"type":"boolean","title":"Gen","description":"Whether this emoji is in the auto-generation pool. Filter gen=true for the subset the server auto-generates."},"k":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"K","description":"Extra search aliases when the source lists any (e.g. \"tada\" for the party popper); omitted otherwise. Name search is the floor; these only widen it."}},"type":"object","required":["c","n","g","gen"],"title":"EmojiEntry","description":"One accepted emoji, enriched for client-side search.\n\nNames and aliases come from the same pinned ``emoji`` package the set\nitself is derived from, so there is no second dataset to keep in sync."},"EmojiSetResponse":{"properties":{"accept_max_version":{"type":"number","title":"Accept Max Version","description":"Newest Unicode emoji version a custom alias may use."},"generate_max_version":{"type":"number","title":"Generate Max Version","description":"Cap for auto-generated emoji aliases (lower, for older platform coverage)."},"max_graphemes":{"type":"integer","title":"Max Graphemes","description":"Maximum number of emoji graphemes allowed in one alias."},"emoji":{"items":{"$ref":"#/components/schemas/EmojiEntry"},"type":"array","title":"Emoji","description":"Every single-codepoint emoji a user may choose, at the acceptance cap, each with its name and whether it is in the generation pool. This is the picker's list. Skin-tone variants are NOT enumerated: the base emoji suffices and skin tone is a client-side modifier appended to the base."}},"type":"object","required":["accept_max_version","generate_max_version","max_graphemes","emoji"],"title":"EmojiSetResponse","description":"The accepted emoji catalogue and its policy caps.\n\nEmoji values are RAW characters in canonical form (no ``U+FE0F``). Each\ncarries its canonical Unicode category (``g``) and the array is ordered by\ncanonical group and within-group order, so a picker can render category\ntabs and open on Smileys rather than symbols."},"ErrorResponse":{"properties":{"error":{"type":"string","title":"Error"},"code":{"type":"string","title":"Code"},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field"},"details":{"anyOf":[{},{"type":"null"}],"title":"Details"}},"type":"object","required":["error","code"],"title":"ErrorResponse","description":"Standard error JSON body produced by the AppError exception handler."},"EventTypeInfoResponse":{"properties":{"type":{"type":"string","title":"Type"},"category":{"type":"string","title":"Category"},"description":{"type":"string","title":"Description"},"frequency":{"type":"string","title":"Frequency"},"sample":{"additionalProperties":true,"type":"object","title":"Sample"}},"type":"object","required":["type","category","description","frequency","sample"],"title":"EventTypeInfoResponse"},"EventTypesResponse":{"properties":{"event_types":{"items":{"$ref":"#/components/schemas/EventTypeInfoResponse"},"type":"array","title":"Event Types"}},"type":"object","required":["event_types"],"title":"EventTypesResponse"},"ExpandResponse":{"properties":{"url":{"type":"string","title":"Url","description":"The URL that was requested."},"final_url":{"type":"string","title":"Final Url"},"final_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Final Status"},"truncated":{"type":"boolean","title":"Truncated","description":"Chain stopped at the redirect cap."},"hops":{"items":{"$ref":"#/components/schemas/ChainHop"},"type":"array","title":"Hops"},"blocklist_match":{"type":"boolean","title":"Blocklist Match"},"web_risk":{"anyOf":[{"$ref":"#/components/schemas/WebRiskVerdict"},{"type":"null"}],"description":"Google Web Risk verdict for the final URL; null when the check didn't run."},"fetched_at":{"type":"string","format":"date-time","title":"Fetched At"}},"type":"object","required":["url","final_url","truncated","hops","blocklist_match","fetched_at"],"title":"ExpandResponse","description":"A URL's redirect chain, every hop listed in order.\n\n``blocklist_match`` is the only safety claim: whether any hop matches\nthe abuse blocklist spoo.me enforces at link creation."},"FeatureState":{"type":"string","enum":["enabled","locked","hidden"],"title":"FeatureState","description":"What a client should do with a gated feature's UI.\n\nENABLED — render it; the account has the feature.\nHIDDEN  — render nothing; the feature does not exist for this account.\nLOCKED  — render it in a locked/upsell state. Reserved: no backend\n          policy emits it until paid plans exist, but it is part of the\n          contract from day one so entitlements later are a data change,\n          not an API version bump."},"FeaturesResponse":{"properties":{"features":{"additionalProperties":{"$ref":"#/components/schemas/FeatureState"},"type":"object","title":"Features"}},"type":"object","required":["features"],"title":"FeaturesResponse","description":"Per-feature availability for the authenticated account.\n\nKeys are the exposed feature names (``services.feature_flag_service.\nEXPOSED_FEATURES``); values tell the client what to render. Clients\nmust treat unknown keys as informational and missing keys as HIDDEN,\nso the feature list can grow without breaking older frontends."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthChecks":{"properties":{"mongodb":{"type":"string","enum":["ok","error","not_configured"],"title":"Mongodb"},"redis":{"type":"string","enum":["ok","error","not_configured"],"title":"Redis"}},"type":"object","required":["mongodb","redis"],"title":"HealthChecks","description":"Individual service check statuses inside HealthResponse."},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status"},"version":{"type":"string","title":"Version"},"checks":{"$ref":"#/components/schemas/HealthChecks"}},"type":"object","required":["status","version","checks"],"title":"HealthResponse","description":"Response body for GET /health."},"LayoutResponse":{"properties":{"layout":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Layout","description":"Saved layout doc, or null when no override exists"}},"type":"object","title":"LayoutResponse"},"LinkStatsResponse":{"properties":{"scope":{"$ref":"#/components/schemas/StatsScope"},"filters":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object","title":"Filters"},"group_by":{"items":{"type":"string"},"type":"array","title":"Group By"},"timezone":{"type":"string","title":"Timezone"},"time_range":{"$ref":"#/components/schemas/StatsTimeRange"},"summary":{"$ref":"#/components/schemas/StatsSummary"},"metrics":{"additionalProperties":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"type":"object","title":"Metrics","description":"Keyed by '{metric}_by_{dimension}' (e.g. 'clicks_by_browser', 'unique_clicks_by_time'). Each value is a list of data-point objects whose keys are the dimension name, the metric name, and '{metric}_percentage'."},"generated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Generated At"},"api_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Version"},"short_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Short Code"},"time_bucket_info":{"anyOf":[{"$ref":"#/components/schemas/TimeBucketInfo"},{"type":"null"}]},"computed_metrics":{"anyOf":[{"$ref":"#/components/schemas/ComputedMetrics"},{"type":"null"}]},"url_id":{"type":"string","title":"Url Id"},"alias":{"type":"string","title":"Alias"}},"type":"object","required":["scope","filters","group_by","timezone","time_range","summary","url_id","alias"],"title":"LinkStatsResponse","description":"Response body for GET /api/v1/stats/links/{url_id}.\n\nThe standard stats wire plus the identity of the selected link.\n``scope`` stays ``all`` — the link is part of the owner's aggregate."},"LoginRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Account email address","examples":["user@example.com"]},"password":{"type":"string","maxLength":255,"title":"Password","description":"Account password","examples":["MySecurePass123!"]}},"type":"object","required":["email","password"],"title":"LoginRequest","description":"Request body for POST /auth/login."},"LoginResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"JWT access token","examples":["eyJhbGciOiJIUzI1NiIs..."]},"user":{"$ref":"#/components/schemas/UserProfileResponse","description":"Authenticated user's profile"}},"type":"object","required":["access_token","user"],"title":"LoginResponse","description":"Response body for POST /auth/login (200)."},"LogoutResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Always true on successful logout"}},"type":"object","required":["success"],"title":"LogoutResponse","description":"Response body for POST /auth/logout (200)."},"MeResponse":{"properties":{"user":{"$ref":"#/components/schemas/UserProfileResponse","description":"Current authenticated user's profile"}},"type":"object","required":["user"],"title":"MeResponse","description":"Response body for GET /auth/me (200)."},"MessageResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["success"],"title":"MessageResponse","description":"Generic success/message response returned by several endpoints."},"MetaTagsRequest":{"properties":{"title":{"type":"string","maxLength":120,"minLength":1,"title":"Title","description":"Preview headline (og:title). Required when meta_tags is set.","examples":["We just launched 🎉"]},"description":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"Description","description":"og:description — roughly 200 chars render on most platforms."},"image":{"anyOf":[{"type":"string","maxLength":700000},{"type":"null"}],"title":"Image","description":"og:image — an https URL, or a `data:image/png|jpeg|webp;base64,` URI which is validated and stored on spoo's CDN. 1200x630 recommended; keep it under 300KB or WhatsApp silently drops it; SVG is rejected (no preview crawler renders it).","examples":["https://example.com/og.png"]},"color":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},{"type":"null"}],"title":"Color","description":"Accent color shown on Discord embeds (theme-color).","examples":["#FF5733"]}},"type":"object","required":["title"],"title":"MetaTagsRequest","description":"Custom social preview (og:title / og:description / og:image / theme-color)."},"MetaTagsResponse":{"properties":{"title":{"type":"string","title":"Title","description":"og:title.","examples":["We just launched 🎉"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"og:description."},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image","description":"og:image URL."},"color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Color","description":"Discord embed accent color.","examples":["#FF5733"]},"warnings":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Warnings","description":"Non-fatal quality notes, e.g. an image WhatsApp may drop."}},"type":"object","required":["title"],"title":"MetaTagsResponse","description":"Custom social-preview settings on a URL (client-visible fields only)."},"MetadataResponse":{"properties":{"url":{"type":"string","title":"Url","description":"The URL that was requested."},"final_url":{"type":"string","title":"Final Url","description":"URL after following redirects."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image","description":"Absolute https URL."},"color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Color","description":"theme-color if #RRGGBB."},"site_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Name"},"html_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Html Title","description":"Raw <title> text, before og/twitter fallbacks."},"html_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Html Description","description":"Plain <meta name=description>, unnormalized."},"favicon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Favicon","description":"Best declared icon (or /favicon.ico); absolute https URL."},"og":{"additionalProperties":{"type":"string"},"type":"object","title":"Og"},"twitter":{"additionalProperties":{"type":"string"},"type":"object","title":"Twitter"},"fetched_at":{"type":"string","format":"date-time","title":"Fetched At"}},"type":"object","required":["url","final_url","fetched_at"],"title":"MetadataResponse","description":"Parsed meta tags of a destination page.\n\n``title``/``description``/``image``/``color``/``site_name`` are the\nnormalized best-picks (og → twitter → html fallbacks) ready to prefill\na link's ``meta_tags``; ``og``/``twitter`` carry the raw families."},"OAuthProvider":{"type":"string","enum":["google","github","discord"],"title":"OAuthProvider","description":"Supported OAuth providers."},"OAuthProviderDetail":{"properties":{"provider":{"$ref":"#/components/schemas/OAuthProvider","description":"Provider name","examples":["google"]},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Email from provider"},"email_verified":{"type":"boolean","title":"Email Verified","description":"Email verified by provider","default":false},"linked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linked At","description":"When the provider was linked"},"profile":{"$ref":"#/components/schemas/ProviderProfile","description":"Provider profile (name, picture)"}},"type":"object","required":["provider"],"title":"OAuthProviderDetail","description":"Detailed OAuth provider entry for the providers list endpoint."},"OAuthProvidersResponse":{"properties":{"providers":{"items":{"$ref":"#/components/schemas/OAuthProviderDetail"},"type":"array","title":"Providers","description":"List of linked OAuth providers with name, email, and linked_at"},"password_set":{"type":"boolean","title":"Password Set","description":"Whether the user has a password set (affects unlink eligibility)"}},"type":"object","required":["providers","password_set"],"title":"OAuthProvidersResponse","description":"Response body for GET /oauth/providers (200)."},"OnboardingCompleteRequest":{"properties":{"heard_from":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Heard From","description":"HDYHAU attribution answer, captured once at completion","examples":["GitHub"]}},"type":"object","title":"OnboardingCompleteRequest","description":"Request body for POST /auth/onboarding/complete."},"OnboardingCompleteResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Always true on success"},"onboarded_at":{"type":"string","title":"Onboarded At","description":"When onboarding was completed (first completion wins)"}},"type":"object","required":["success","onboarded_at"],"title":"OnboardingCompleteResponse","description":"Response body for POST /auth/onboarding/complete (200)."},"OnboardingStateRequest":{"properties":{"step":{"type":"string","enum":["welcome","path","link","api","domain","claim","apps","recap"],"title":"Step","description":"Wizard step the user is currently on","examples":["domain"]},"path":{"anyOf":[{"type":"string","enum":["links","api"]},{"type":"null"}],"title":"Path","description":"Chosen onboarding path, once the user has forked","examples":["links"]}},"type":"object","required":["step"],"title":"OnboardingStateRequest","description":"Request body for PUT /auth/onboarding."},"OnboardingStateResponse":{"properties":{"step":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Step","description":"Stored wizard step","examples":["link"]},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Path","description":"Chosen path (links or api)","examples":["links"]}},"type":"object","title":"OnboardingStateResponse","description":"Response body for GET/PUT /auth/onboarding (200).\n\nA resume pointer, nothing more. Empty (step=null) means nothing to\nresume: never started, expired, or already completed — completion is\na permanent account fact exposed as ``user.onboarded_at`` on\n/auth/me, not part of this cache."},"PreviewDestination":{"properties":{"url":{"type":"string","title":"Url"},"domain":{"type":"string","title":"Domain"},"path":{"type":"string","title":"Path"},"is_https":{"type":"boolean","title":"Is Https"}},"type":"object","required":["url","domain","path","is_https"],"title":"PreviewDestination","description":"A destination URL split into display parts."},"PreviewGeoDestination":{"properties":{"url":{"type":"string","title":"Url"},"domain":{"type":"string","title":"Domain"},"path":{"type":"string","title":"Path"},"is_https":{"type":"boolean","title":"Is Https"},"countries":{"items":{"type":"string"},"type":"array","title":"Countries"}},"type":"object","required":["url","domain","path","is_https","countries"],"title":"PreviewGeoDestination","description":"One geo-rule destination group.\n\n``countries`` are ISO 3166-1 alpha-2 codes, sorted ascending — every\nrule is listed, nothing summarized (anti-cloaking transparency)."},"PreviewVariantDestination":{"properties":{"url":{"type":"string","title":"Url"},"domain":{"type":"string","title":"Domain"},"path":{"type":"string","title":"Path"},"is_https":{"type":"boolean","title":"Is Https"},"weight":{"type":"integer","title":"Weight"}},"type":"object","required":["url","domain","path","is_https","weight"],"title":"PreviewVariantDestination","description":"One A/B variant destination with its traffic share in percent."},"ProfilePictureMessageResponse":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"ProfilePictureMessageResponse"},"ProviderProfile":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"picture":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Picture"}},"type":"object","title":"ProviderProfile","description":"Nested profile data stored per OAuth provider."},"PublicLinkFacts":{"properties":{"alias":{"type":"string","title":"Alias"},"short_url":{"type":"string","title":"Short Url"},"long_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Long Url"},"expired_redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expired Redirect Url"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"status":{"type":"string","enum":["active","inactive","expired","blocked","scheduled"],"title":"Status"},"max_clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Clicks"},"block_bots":{"type":"boolean","title":"Block Bots"},"password_protected":{"type":"boolean","title":"Password Protected"}},"type":"object","required":["alias","short_url","status","block_bots","password_protected"],"title":"PublicLinkFacts","description":"Public facts about the link shown above the charts."},"PublicPreviewResponse":{"properties":{"generation":{"type":"string","enum":["v1","v2"],"title":"Generation"},"alias":{"type":"string","title":"Alias"},"short_url":{"type":"string","title":"Short Url"},"status":{"type":"string","enum":["active","inactive","expired","blocked","scheduled"],"title":"Status"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"starts_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Starts At"},"password_protected":{"type":"boolean","title":"Password Protected"},"destination":{"anyOf":[{"$ref":"#/components/schemas/PreviewDestination"},{"type":"null"}]},"geo_destinations":{"anyOf":[{"items":{"$ref":"#/components/schemas/PreviewGeoDestination"},"type":"array"},{"type":"null"}],"title":"Geo Destinations"},"variant_destinations":{"anyOf":[{"items":{"$ref":"#/components/schemas/PreviewVariantDestination"},"type":"array"},{"type":"null"}],"title":"Variant Destinations"},"expired_destination":{"anyOf":[{"$ref":"#/components/schemas/PreviewDestination"},{"type":"null"}]}},"type":"object","required":["generation","alias","short_url","status","created_at","password_protected","destination","geo_destinations"],"title":"PublicPreviewResponse","description":"Response body for the public link preview endpoint.\n\n``destination``, ``geo_destinations`` and ``variant_destinations`` are\nnon-null only while the link is active and not password-protected — the\npreview never reveals a destination the redirect would refuse to serve.\nThe rule runs both ways: ``expired_destination`` names where an expired\nlink still sends every visitor when its owner set a fallback, so the\npreview never shows LESS than the redirect serves either."},"PublicStatsBody":{"properties":{"password":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Password","description":"Password for a password-protected link's stats."}},"type":"object","title":"PublicStatsBody","description":"Optional JSON body carrying the stats-page password."},"PublicStatsResponse":{"properties":{"generation":{"type":"string","enum":["v1","v2"],"title":"Generation"},"link":{"$ref":"#/components/schemas/PublicLinkFacts"},"stats":{"additionalProperties":true,"type":"object","title":"Stats","description":"The modern stats wire shape (same as GET /api/v1/stats): summary, metrics keyed '{metric}_by_{dimension}', time_range, time_bucket_info, computed_metrics. v1 links carry a 'clicks_by_bots' dimension and no 'city'/'device'; v2 the reverse."}},"type":"object","required":["generation","link","stats"],"title":"PublicStatsResponse","description":"Response body for GET|POST /api/v1/public/stats/{short_code}."},"PutLayoutRequest":{"properties":{"layout":{"additionalProperties":true,"type":"object","title":"Layout","description":"Opaque layout document owned by the client. The server stores it verbatim; versioning happens inside the document.","examples":[{"version":1,"widgets":[]}]}},"type":"object","required":["layout"],"title":"PutLayoutRequest"},"RefreshResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"New JWT access token","examples":["eyJhbGciOiJIUzI1NiIs..."]}},"type":"object","required":["access_token"],"title":"RefreshResponse","description":"Response body for POST /auth/refresh (200)."},"RegisterRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Email address for the new account","examples":["newuser@example.com"]},"password":{"type":"string","maxLength":128,"title":"Password","description":"Password (min 8 chars, must contain letter + number + special char)","examples":["MySecurePass123!"]},"user_name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"User Name","description":"Display name (optional)","examples":["Jane Doe"]}},"type":"object","required":["email","password"],"title":"RegisterRequest","description":"Request body for POST /auth/register."},"RegisterResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"JWT access token","examples":["eyJhbGciOiJIUzI1NiIs..."]},"user":{"$ref":"#/components/schemas/UserProfileResponse","description":"Newly created user's profile"},"requires_verification":{"type":"boolean","title":"Requires Verification","description":"Whether email verification is required before accessing protected resources"},"verification_sent":{"type":"boolean","title":"Verification Sent","description":"Whether the verification email was sent successfully"}},"type":"object","required":["access_token","user","requires_verification","verification_sent"],"title":"RegisterResponse","description":"Response body for POST /auth/register (201)."},"RejectedReportItem":{"properties":{"index":{"type":"integer","title":"Index"},"input":{"type":"string","title":"Input"},"code":{"type":"string","enum":["invalid_input","not_found","duplicate_in_batch"],"title":"Code"}},"type":"object","required":["index","input","code"],"title":"RejectedReportItem","description":"One rejected entry in the per-item breakdown.\n\n``index`` refers to the item's position in the submitted ``items``\narray; ``input`` echoes the raw ``code_or_url`` so bulk clients can\nline results up without keeping their own index map."},"ReportItemRequest":{"properties":{"code_or_url":{"type":"string","maxLength":2048,"minLength":1,"title":"Code Or Url","description":"Bare short code or full short URL — custom-domain URLs included (e.g. `abc123`, `spoo.me/abc123`, `https://go.customer.com/deal`)","examples":["abc123","https://spoo.me/abc123"]},"reason":{"$ref":"#/components/schemas/ReportReason","description":"Reporter-claimed reason (triage hint)"},"details":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Details","description":"Optional free-text context"},"vector":{"anyOf":[{"$ref":"#/components/schemas/ReportVector"},{"type":"null"}],"description":"How the link reached the reporter"}},"type":"object","required":["code_or_url","reason"],"title":"ReportItemRequest","description":"One reported link inside POST /api/v1/reports."},"ReportReason":{"type":"string","enum":["phishing","malware","spam","illegal_content","other"],"title":"ReportReason","description":"Reporter-claimed reason, aligned with the safety framework's harm\ntiers so intake slots into the funnel without a translation layer."},"ReportSubmissionResponse":{"properties":{"submission_id":{"type":"string","title":"Submission Id","description":"Opaque submission reference"},"accepted":{"type":"integer","title":"Accepted","description":"Number of items stored"},"rejected":{"items":{"$ref":"#/components/schemas/RejectedReportItem"},"type":"array","title":"Rejected","description":"Per-item rejections (empty when everything was accepted)"}},"type":"object","required":["submission_id","accepted","rejected"],"title":"ReportSubmissionResponse","description":"Response body for POST /api/v1/reports.\n\nBad codes don't sink the batch: accepted items are stored even when\nothers are rejected, and the breakdown says which and why."},"ReportVector":{"type":"string","enum":["sms","email","dm","social","web","other"],"title":"ReportVector","description":"How the link reached the reporter — the delivery-vector hint the\n451 page's scam-awareness story needs."},"RequestPasswordResetRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Email address of the account to reset","examples":["user@example.com"]}},"type":"object","required":["email"],"title":"RequestPasswordResetRequest","description":"Request body for POST /auth/request-password-reset."},"ResetPasswordRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Email address of the account","examples":["user@example.com"]},"code":{"type":"string","pattern":"^[0-9]{6}$","title":"Code","description":"6-digit OTP from password reset email","examples":["123456"]},"password":{"type":"string","maxLength":128,"title":"Password","description":"New password (min 8 chars, must contain letter + number + special char)","examples":["NewSecurePass456!"]}},"type":"object","required":["email","code","password"],"title":"ResetPasswordRequest","description":"Request body for POST /auth/reset-password."},"RestoreAccountRequest":{"properties":{"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email","description":"Account email address (credential restore)","examples":["user@example.com"]},"password":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Password","description":"Account password (credential restore)","examples":["MySecurePass123!"]},"restore_token":{"anyOf":[{"type":"string","maxLength":128,"minLength":16},{"type":"null"}],"title":"Restore Token","description":"One-shot restore token from the deletion notice email (token restore — OAuth-only accounts)"}},"type":"object","title":"RestoreAccountRequest","description":"Request body for POST /auth/restore.\n\nExactly one restore proof: ``email`` + ``password`` for accounts with\na password, or ``restore_token`` (the one-shot token from the\ndeletion notice email — the only path for OAuth-only accounts).\nMixing or omitting both is a validation error, not a 403."},"SendVerificationResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the verification email was sent"},"message":{"type":"string","title":"Message","description":"Human-readable status message"},"expires_in":{"type":"integer","title":"Expires In","description":"OTP expiry duration in seconds","examples":[600]}},"type":"object","required":["success","message","expires_in"],"title":"SendVerificationResponse","description":"Response body for POST /auth/send-verification (200)."},"SetPasswordRequest":{"properties":{"password":{"type":"string","maxLength":128,"title":"Password","description":"New password (min 8 chars, must contain letter + number + special char)","examples":["MySecurePass123!"]}},"type":"object","required":["password"],"title":"SetPasswordRequest","description":"Request body for POST /auth/set-password.\n\nOnly applies to OAuth-only users who have not yet set a password."},"SetProfilePictureRequest":{"properties":{"picture_id":{"type":"string","maxLength":200,"minLength":1,"title":"Picture Id"}},"type":"object","required":["picture_id"],"title":"SetProfilePictureRequest"},"StatsResponse":{"properties":{"scope":{"$ref":"#/components/schemas/StatsScope"},"filters":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object","title":"Filters"},"group_by":{"items":{"type":"string"},"type":"array","title":"Group By"},"timezone":{"type":"string","title":"Timezone"},"time_range":{"$ref":"#/components/schemas/StatsTimeRange"},"summary":{"$ref":"#/components/schemas/StatsSummary"},"metrics":{"additionalProperties":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"type":"object","title":"Metrics","description":"Keyed by '{metric}_by_{dimension}' (e.g. 'clicks_by_browser', 'unique_clicks_by_time'). Each value is a list of data-point objects whose keys are the dimension name, the metric name, and '{metric}_percentage'."},"generated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Generated At"},"api_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Version"},"short_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Short Code"},"time_bucket_info":{"anyOf":[{"$ref":"#/components/schemas/TimeBucketInfo"},{"type":"null"}]},"computed_metrics":{"anyOf":[{"$ref":"#/components/schemas/ComputedMetrics"},{"type":"null"}]}},"type":"object","required":["scope","filters","group_by","timezone","time_range","summary"],"title":"StatsResponse","description":"Response body for GET /api/v1/stats.\n\n``metrics`` uses dynamic keys ({metric}_by_{dimension}), each mapping to a\nlist of data-point dicts.  Optional fields (``short_code``,\n``time_bucket_info``, ``computed_metrics``) are absent when not applicable."},"StatsScope":{"type":"string","enum":["all","anon"],"title":"StatsScope","description":"Stats wire scope.\n\nResponse-only: the ``scope`` request parameter no longer exists (auth\nis mandatory), but the response wire keeps its ``scope`` key and the\npublic stats endpoint's frozen contract still carries ``anon``."},"StatsSummary":{"properties":{"total_clicks":{"type":"integer","title":"Total Clicks"},"unique_clicks":{"type":"integer","title":"Unique Clicks"},"first_click":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Click"},"last_click":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Click"},"avg_redirection_time":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Redirection Time"}},"type":"object","required":["total_clicks","unique_clicks"],"title":"StatsSummary","description":"Summary statistics block inside StatsResponse."},"StatsTimeRange":{"properties":{"start_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Date"},"end_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Date"}},"type":"object","title":"StatsTimeRange","description":"Time range metadata inside StatsResponse."},"TagColor":{"type":"string","enum":["gray","red","orange","amber","green","teal","blue","violet","pink"],"title":"TagColor","description":"Fixed palette; the dashboard maps each key to a muted dot colour."},"TagDeleteResponse":{"properties":{"deleted":{"type":"boolean","title":"Deleted","default":true},"links_updated":{"type":"integer","title":"Links Updated","description":"Links the tag was removed from."}},"type":"object","required":["links_updated"],"title":"TagDeleteResponse"},"TagIcon":{"type":"string","enum":["banknote","bar-chart-3","beaker","bell","bird","book","bookmark","box","briefcase","bug","building","calendar","camera","car","cat","clock","cloud","code","coffee","compass","credit-card","crown","dog","file-text","fish","flag","flame","flask-conical","folder","gamepad-2","gem","ghost","gift","globe","graduation-cap","handshake","hash","heart","home","hourglass","image","key","layers","leaf","lightbulb","link","lock","mail","map-pin","megaphone","message-square","mic","moon","music","newspaper","package","pen-line","phone","pie-chart","pizza","plane","puzzle","receipt","rocket","send","settings","share-2","shield","shopping-cart","smile","sparkles","star","store","sun","tag","target","terminal","timer","trending-up","trophy","umbrella","user","users","video","wallet","wrench","zap"],"title":"TagIcon"},"TagListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TagResponse"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"TagListResponse"},"TagRef":{"properties":{"id":{"type":"string","title":"Id","examples":["665f0c2f9e7a4b1d2c3d4e5f"]},"name":{"type":"string","title":"Name","examples":["launch"]},"color":{"$ref":"#/components/schemas/TagColor","examples":["violet"]},"icon":{"$ref":"#/components/schemas/TagIcon","examples":["rocket"]}},"type":"object","required":["id","name","color","icon"],"title":"TagRef","description":"A tag as it appears on a link: enough to render, no counts."},"TagResponse":{"properties":{"id":{"type":"string","title":"Id","examples":["665f0c2f9e7a4b1d2c3d4e5f"]},"name":{"type":"string","title":"Name","examples":["launch"]},"color":{"$ref":"#/components/schemas/TagColor","examples":["violet"]},"icon":{"$ref":"#/components/schemas/TagIcon","examples":["rocket"]},"link_count":{"type":"integer","title":"Link Count","description":"Links carrying the tag.","examples":[14]},"created_at":{"type":"string","title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","name","color","icon","link_count","created_at"],"title":"TagResponse","description":"A tag on its own endpoints, with its link count."},"TestWebhookRequest":{"properties":{"event_type":{"type":"string","title":"Event Type","description":"Any catalog event type — its documented sample payload is sent through the real pipeline — or `webhook.test`.","default":"webhook.test","examples":["link.clicked"]}},"type":"object","title":"TestWebhookRequest"},"TimeBucketInfo":{"properties":{"strategy":{"type":"string","title":"Strategy"},"mongo_format":{"type":"string","title":"Mongo Format"},"display_format":{"type":"string","title":"Display Format"},"timezone":{"type":"string","title":"Timezone"},"interval_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Interval Minutes"}},"type":"object","required":["strategy","mongo_format","display_format","timezone"],"title":"TimeBucketInfo","description":"Time bucketing metadata — only present when 'time' is in group_by."},"UpdateCustomDomainRequest":{"properties":{"root_redirect":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Root Redirect","description":"Destination URL for `GET /` on the custom domain. Returns 302. Pass `null` to clear. Field omitted leaves current value.","examples":["https://acme.com/landing"]},"not_found_redirect":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Not Found Redirect","description":"Fallback URL for any path not matching an alias. Returns 302 instead of the default 404. Pass `null` to clear.","examples":["https://acme.com/404"]},"custom_robots_txt":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"title":"Custom Robots Txt","description":"Override the default `User-agent: *\\nDisallow: /` body served at /robots.txt. Capped at 4096 chars. Pass `null` to clear. Note: responses to alias redirects always carry `X-Robots-Tag: noindex, nofollow, noarchive` regardless of this field — short URLs are pure redirects with no indexable content."}},"type":"object","title":"UpdateCustomDomainRequest","description":"Body for ``PATCH /api/v1/custom-domains/{id}``.\n\nPartial update: callers send only the fields they want to change.\nField omitted = leave doc value as-is. Field explicitly ``null`` = clear\nthe stored value. The service distinguishes the two via ``model_fields_set``."},"UpdateProfileRequest":{"properties":{"user_name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"User Name","description":"New display name, or null to clear it","examples":["Jane Doe"]}},"type":"object","required":["user_name"],"title":"UpdateProfileRequest","description":"Request body for PATCH /auth/me.\n\n``user_name`` is required but nullable: an explicit ``null`` clears\nthe display name (an accidental ``{}`` must not). Bounds mirror\nRegisterRequest — the two write paths for the same field."},"UpdateTagRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Name","description":"Tag name, at most 32 characters. Lowercased and trimmed on write; letters, digits, spaces, `-`, `_` and `.` only. Unique per account."},"color":{"anyOf":[{"$ref":"#/components/schemas/TagColor"},{"type":"null"}],"description":"One of the palette keys. Omit on create to get the least-used colour in your account."},"icon":{"$ref":"#/components/schemas/TagIcon","title":"Icon","description":"Icon key from the curated set (lucide names). Defaults to `tag`."}},"type":"object","title":"UpdateTagRequest","description":"Rename, recolour or change the icon. Omitted fields are left as they are."},"UpdateUrlRequest":{"properties":{"long_url":{"anyOf":[{"type":"string","maxLength":8192},{"type":"null"}],"title":"Long Url","description":"New destination URL. Must be a valid http:// or https:// URL.","examples":["https://example.com/updated/url"]},"alias":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Alias","description":"New custom short code (alphanumeric 3-16 chars, or emoji-only 1-15 emoji). Pass `null` to keep existing. Must be unique and available.","examples":["newlink","🚀🔥"]},"password":{"anyOf":[{"type":"string","maxLength":128,"minLength":8},{"type":"null"}],"title":"Password","description":"New password. Pass `null` to remove password protection.","examples":["newPass@456"]},"block_bots":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Block Bots","description":"Block known bot user agents. Pass `null` to keep existing setting."},"max_clicks":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Max Clicks","description":"New click limit. Pass `0` or `null` to remove the limit.","examples":[500]},"expire_after":{"anyOf":[{"type":"string","format":"date-time"},{"type":"integer"},{"type":"null"}],"title":"Expire After","description":"Expiration time. ISO 8601 string (e.g. `2025-12-31T23:59:59Z`) or Unix epoch seconds (e.g. `1735689599`). Pass `null` to remove.","examples":["2025-12-31T23:59:59Z",1735689599]},"starts_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"integer"},{"type":"null"}],"title":"Starts At","description":"Go-live time. ISO 8601 string or Unix epoch seconds; must be in the future and before `expire_after`. Pass `null` to make the link live now.","examples":["2026-09-10T18:00:00+05:30",1789500000]},"pre_start_url":{"anyOf":[{"type":"string","maxLength":8192},{"type":"null"}],"title":"Pre Start Url","description":"Where visitors are sent before `starts_at`. Pass `null` for the not-yet-live page.","examples":["https://example.com/coming-soon"]},"private_stats":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Private Stats","description":"Make statistics private (only owner can view). Pass `null` to keep existing."},"status":{"anyOf":[{"type":"string","enum":["ACTIVE","INACTIVE"]},{"type":"null"}],"title":"Status","description":"URL status. ACTIVE enables redirects, INACTIVE disables them.","examples":["ACTIVE"]},"domain":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"title":"Domain","description":"Move the URL to a different domain namespace. Pass an owned ACTIVE custom-domain fqdn (e.g. `links.acme.com`) to move it there, or `null`/empty to move it back to the system default. Alias must be available on the target domain.","examples":["links.acme.com"]},"geo_rules":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Geo Rules","description":"Per-country destination overrides: ISO 3166-1 alpha-2 country code → destination URL (at most 50 entries by default). The map replaces any existing rules in full. Pass `null` or `{}` to remove all rules; omit to keep existing rules unchanged.","examples":[{"IN":"https://example.in/","US":"https://example.com/us"}]},"expired_redirect_url":{"anyOf":[{"type":"string","maxLength":8192},{"type":"null"}],"title":"Expired Redirect Url","description":"Where visitors land once the link has expired, by time or by click limit, instead of the expired page. Validated like a destination. Pass `null` or empty to remove; omit to keep.","examples":["https://example.com/offer-ended"]},"tag_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tag Ids","description":"Ids of tags from `GET /api/v1/tags`, at most 10 per link. Every id must be one of your tags (400 otherwise). On PATCH the list replaces the stored one; `null` or `[]` clears it.","examples":[["665f0c2f9e7a4b1d2c3d4e5f"]]},"ab_variants":{"anyOf":[{"items":{"$ref":"#/components/schemas/AbVariantRequest"},"type":"array"},{"type":"null"}],"title":"Ab Variants","description":"Weighted split destinations: each entry is `{url, weight}` where `weight` is the percentage of visitors sent there (integers, summing to at most 100). The default destination (`url`) receives the remainder. Requires authentication. The list replaces any existing variants in full. Pass `null` or `[]` to remove all variants; omit to keep them unchanged.","examples":[[{"url":"https://example.com/b","weight":40}]]},"meta_tags":{"anyOf":[{"$ref":"#/components/schemas/MetaTagsRequest"},{"type":"null"}],"description":"Custom social preview served to link-preview crawlers (WhatsApp, Discord, Slack, iMessage, …). The object replaces the whole setting; on PATCH pass null to remove. Requires a verified account with the feature enabled. Note: platforms cache previews for ~7-30 days — edits propagate slowly (the Facebook Sharing Debugger, LinkedIn Post Inspector, and Telegram's @WebpageBot force a refresh)."}},"type":"object","title":"UpdateUrlRequest","description":"Request body for partially updating an existing shortened URL.\n\nAll fields are optional; only provided fields are updated.\nPass ``max_clicks=0`` or ``max_clicks=null`` to remove the limit.\nPass ``password=null`` (or omit) to remove password protection."},"UpdateUrlResponse":{"properties":{"id":{"type":"string","title":"Id","description":"MongoDB ObjectId of the URL.","examples":["507f1f77bcf86cd799439011"]},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alias","description":"Short code.","examples":["mylink"]},"long_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Long Url","description":"Destination URL.","examples":["https://example.com/long/url"]},"status":{"anyOf":[{"$ref":"#/components/schemas/UrlStatus"},{"type":"null"}],"description":"URL status. Derived — reflects time and max-click expiry even before the stored flip is persisted.","examples":["ACTIVE"]},"password_set":{"type":"boolean","title":"Password Set","description":"Whether the URL is password-protected."},"max_clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Clicks","description":"Click limit, or null if unlimited.","examples":[100]},"expire_after":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expire After","description":"Expiration as Unix timestamp, or null.","examples":[1735689599]},"starts_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Starts At","description":"Go-live time as Unix timestamp, or null when live now.","examples":[1789500000]},"pre_start_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pre Start Url","description":"Where visitors go before `starts_at`, or null for the not-yet-live page.","examples":["https://example.com/coming-soon"]},"block_bots":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Block Bots","description":"Whether bot blocking is enabled."},"private_stats":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Private Stats","description":"Whether statistics are private."},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Domain fqdn the URL is served on. Null for the system default.","examples":["links.acme.com"]},"geo_rules":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Geo Rules","description":"Per-country destination overrides (ISO alpha-2 code → URL), or null.","examples":[{"IN":"https://example.in/"}]},"expired_redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expired Redirect Url","description":"Destination served once the link has expired, or null.","examples":["https://example.com/offer-ended"]},"tags":{"items":{"$ref":"#/components/schemas/TagRef"},"type":"array","title":"Tags","description":"The link's tags (id, name, colour), in the link's order."},"ab_variants":{"anyOf":[{"items":{"$ref":"#/components/schemas/AbVariantResponse"},"type":"array"},{"type":"null"}],"title":"Ab Variants","description":"Weighted split destinations ({url, weight} entries; the default destination takes the remaining share), or null.","examples":[[{"url":"https://example.com/b","weight":40}]]},"updated_at":{"type":"integer","title":"Updated At","description":"Last update time as Unix timestamp.","examples":[1704067200]},"meta_tags":{"anyOf":[{"$ref":"#/components/schemas/MetaTagsResponse"},{"type":"null"}],"description":"Custom social preview, if configured."}},"type":"object","required":["id","password_set","updated_at"],"title":"UpdateUrlResponse","description":"Response body after a successful URL update (PATCH /api/v1/urls/{url_id})."},"UpdateUrlStatusRequest":{"properties":{"status":{"type":"string","enum":["ACTIVE","INACTIVE"],"title":"Status","description":"New status for the URL. `ACTIVE` enables redirects, `INACTIVE` disables them.","examples":["ACTIVE"]}},"type":"object","required":["status"],"title":"UpdateUrlStatusRequest","description":"Request body for updating only the status of a shortened URL."},"UpdateWebhookEndpointRequest":{"properties":{"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"events":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":32,"minItems":1},{"type":"null"}],"title":"Events"},"description":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Description"},"scope_links":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":256},{"type":"null"}],"title":"Scope Links"},"flavor":{"anyOf":[{"$ref":"#/components/schemas/WebhookFlavor"},{"type":"null"}]},"status":{"anyOf":[{"$ref":"#/components/schemas/WebhookStatus"},{"type":"null"}],"description":"`active` or `paused`. `disabled` is system-set."}},"type":"object","title":"UpdateWebhookEndpointRequest","description":"All fields optional; only provided fields change. `scope_links: null`\nis 'all links' — to keep an existing scope, omit the field."},"UploadProfilePictureRequest":{"properties":{"image":{"type":"string","minLength":1,"title":"Image","description":"base64 data URI (image/png, image/jpeg, image/webp)"}},"type":"object","required":["image"],"title":"UploadProfilePictureRequest"},"UrlListItem":{"properties":{"id":{"type":"string","title":"Id"},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alias"},"long_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Long Url"},"status":{"anyOf":[{"$ref":"#/components/schemas/UrlStatus"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"expire_after":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expire After"},"starts_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Starts At"},"pre_start_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pre Start Url"},"max_clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Clicks"},"private_stats":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Private Stats"},"block_bots":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Block Bots"},"password_set":{"type":"boolean","title":"Password Set"},"total_clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Clicks"},"last_click":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Click"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"geo_rules":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Geo Rules"},"expired_redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expired Redirect Url"},"tags":{"items":{"$ref":"#/components/schemas/TagRef"},"type":"array","title":"Tags"},"ab_variants":{"anyOf":[{"items":{"$ref":"#/components/schemas/AbVariantResponse"},"type":"array"},{"type":"null"}],"title":"Ab Variants"},"meta_tags":{"anyOf":[{"$ref":"#/components/schemas/MetaTagsResponse"},{"type":"null"}]}},"type":"object","required":["id","password_set"],"title":"UrlListItem","description":"A single URL entry inside UrlListResponse.items.\n\n``created_at`` and ``last_click`` are ISO 8601 strings (e.g. \"2024-01-01T00:00:00Z\").\n``expire_after`` is a Unix timestamp integer or null.\nThese formats match the existing endpoint exactly.\n``status`` is derived — it reflects time and max-click expiry even\nbefore the stored flip is persisted."},"UrlListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/UrlListItem"},"type":"array","title":"Items"},"page":{"type":"integer","title":"Page"},"pageSize":{"type":"integer","title":"Pagesize"},"total":{"type":"integer","title":"Total"},"hasNext":{"type":"boolean","title":"Hasnext"},"sortBy":{"type":"string","title":"Sortby"},"sortOrder":{"type":"string","title":"Sortorder"}},"type":"object","required":["items","page","pageSize","total","hasNext","sortBy","sortOrder"],"title":"UrlListResponse","description":"Response body for GET /api/v1/urls.\n\nUses camelCase field names to match the existing Flask endpoint exactly.\nField names are camelCase here (not snake_case + alias) because this is a\nresponse-only model — we build it explicitly in the route handler."},"UrlResponse":{"properties":{"id":{"type":"string","title":"Id","description":"MongoDB ObjectId of the URL — the identifier the management endpoints (`/urls/{url_id}`) address it by.","examples":["507f1f77bcf86cd799439011"]},"alias":{"type":"string","title":"Alias","description":"Short code for the URL.","examples":["mylink"]},"short_url":{"type":"string","title":"Short Url","description":"Full shortened URL ready for sharing. Emoji aliases appear unencoded (clients/browsers percent-encode on use).","examples":["https://spoo.me/mylink","https://spoo.me/🚀🔥"]},"long_url":{"type":"string","title":"Long Url","description":"Original destination URL.","examples":["https://example.com/long/url"]},"owner_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Id","description":"User ID if authenticated, null for anonymous URLs.","examples":["507f1f77bcf86cd799439011"]},"created_at":{"type":"integer","title":"Created At","description":"Creation time as Unix timestamp.","examples":[1704067200]},"status":{"$ref":"#/components/schemas/UrlStatus","description":"URL status. Derived — reflects time and max-click expiry even before the stored flip is persisted.","examples":["ACTIVE"]},"private_stats":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Private Stats","description":"Whether statistics are private (owner-only)."},"geo_rules":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Geo Rules","description":"Per-country destination overrides (ISO alpha-2 code → URL), or null.","examples":[{"IN":"https://example.in/"}]},"expired_redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expired Redirect Url","description":"Destination served once the link has expired, or null.","examples":["https://example.com/offer-ended"]},"tags":{"items":{"$ref":"#/components/schemas/TagRef"},"type":"array","title":"Tags","description":"The link's tags (id, name, colour), in the link's order."},"ab_variants":{"anyOf":[{"items":{"$ref":"#/components/schemas/AbVariantResponse"},"type":"array"},{"type":"null"}],"title":"Ab Variants","description":"Weighted split destinations ({url, weight} entries; the default destination takes the remaining share), or null.","examples":[[{"url":"https://example.com/b","weight":40}]]},"meta_tags":{"anyOf":[{"$ref":"#/components/schemas/MetaTagsResponse"},{"type":"null"}],"description":"Custom social preview, if configured."},"claim_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claim Token","description":"One-time bearer proof of creation — your deed to this link. Present only on anonymous creates, shown exactly once (only its hash is retained server-side). Store it to later attach the link to an account via POST /api/v1/urls/claim; null for authenticated creates."}},"type":"object","required":["id","alias","short_url","long_url","created_at","status"],"title":"UrlResponse","description":"Response body for a newly created shortened URL (POST /api/v1/shorten).\n\n``created_at`` is a Unix timestamp integer — matching the existing endpoint."},"UrlStatus":{"type":"string","enum":["ACTIVE","INACTIVE","EXPIRED","BLOCKED","SCHEDULED"],"title":"UrlStatus","description":"Status values for v2 URLs."},"UserPfp":{"properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Profile picture URL","examples":["https://lh3.googleusercontent.com/a/photo"]},"source":{"anyOf":[{"$ref":"#/components/schemas/OAuthProvider"},{"type":"string","const":"upload"},{"type":"null"}],"title":"Source","description":"Source of the profile picture — an OAuth provider or `upload`","examples":["google"]}},"type":"object","title":"UserPfp","description":"Profile picture info returned inside UserProfileResponse."},"UserProfileResponse":{"properties":{"id":{"type":"string","title":"Id","description":"User ID","examples":["507f1f77bcf86cd799439011"]},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"User's email address","examples":["user@example.com"]},"email_verified":{"type":"boolean","title":"Email Verified","description":"Whether the email address has been verified"},"user_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Name","description":"Display name","examples":["Jane Doe"]},"plan":{"type":"string","title":"Plan","description":"Subscription plan","examples":["free"]},"password_set":{"type":"boolean","title":"Password Set","description":"Whether the user has set a password"},"onboarded_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Onboarded At","description":"When the user completed onboarding (null = never)"},"auth_providers":{"items":{"$ref":"#/components/schemas/AuthProviderInfo"},"type":"array","title":"Auth Providers","description":"Linked OAuth providers"},"pfp":{"anyOf":[{"$ref":"#/components/schemas/UserPfp"},{"type":"null"}],"description":"Profile picture (absent when not set)"}},"type":"object","required":["id","email_verified","plan","password_set","auth_providers"],"title":"UserProfileResponse","description":"User profile shape — used in login/register/me responses."},"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"},"VerificationMethod":{"type":"string","enum":["cname","a_record","txt_challenge","system","cf_delegated_dcv","cf_http_dcv"],"title":"VerificationMethod","description":"How ownership of the fqdn is proven before activation."},"VerifyEmailRequest":{"properties":{"code":{"type":"string","pattern":"^[0-9]{6}$","title":"Code","description":"6-digit OTP from verification email","examples":["123456"]}},"type":"object","required":["code"],"title":"VerifyEmailRequest","description":"Request body for POST /auth/verify-email.\n\n``code`` is the 6-digit OTP sent to the user's email address."},"VerifyEmailResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether verification succeeded"},"message":{"type":"string","title":"Message","description":"Human-readable status message","examples":["email verified successfully"]},"email_verified":{"type":"boolean","title":"Email Verified","description":"Updated email verification status (always true on success)"}},"type":"object","required":["success","message","email_verified"],"title":"VerifyEmailResponse","description":"Response body for POST /auth/verify-email (200)."},"WebRiskVerdict":{"properties":{"checked":{"type":"boolean","title":"Checked"},"threats":{"items":{"type":"string"},"type":"array","title":"Threats"}},"type":"object","required":["checked"],"title":"WebRiskVerdict"},"WebhookDeliveryResponse":{"properties":{"id":{"type":"string","title":"Id"},"webhook_id":{"type":"string","title":"Webhook Id"},"event_type":{"type":"string","title":"Event Type"},"is_test":{"type":"boolean","title":"Is Test"},"status":{"$ref":"#/components/schemas/DeliveryStatus"},"attempt_count":{"type":"integer","title":"Attempt Count"},"attempts":{"items":{"$ref":"#/components/schemas/DeliveryAttemptResponse"},"type":"array","title":"Attempts"},"next_attempt_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Attempt At"},"rendered_body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rendered Body"},"created_at":{"type":"integer","title":"Created At"}},"type":"object","required":["id","webhook_id","event_type","is_test","status","attempt_count","attempts","created_at"],"title":"WebhookDeliveryResponse"},"WebhookEndpointCreatedResponse":{"properties":{"id":{"type":"string","title":"Id"},"url":{"type":"string","title":"Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"events":{"items":{"type":"string"},"type":"array","title":"Events"},"scope_links":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scope Links","description":"Null means all links, including future ones."},"flavor":{"$ref":"#/components/schemas/WebhookFlavor"},"status":{"$ref":"#/components/schemas/WebhookStatus"},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disabled Reason"},"signing_secret_prefix":{"type":"string","title":"Signing Secret Prefix"},"consecutive_failures":{"type":"integer","title":"Consecutive Failures"},"total_deliveries":{"type":"integer","title":"Total Deliveries"},"total_successes":{"type":"integer","title":"Total Successes"},"last_delivery_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Delivery At"},"last_success_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Success At"},"last_failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Failure Reason"},"created_at":{"type":"integer","title":"Created At"},"signing_secret":{"type":"string","title":"Signing Secret","description":"The full signing secret — shown ONCE, never retrievable again. Store it; you need it to verify webhook signatures."}},"type":"object","required":["id","url","events","flavor","status","signing_secret_prefix","consecutive_failures","total_deliveries","total_successes","created_at","signing_secret"],"title":"WebhookEndpointCreatedResponse"},"WebhookEndpointResponse":{"properties":{"id":{"type":"string","title":"Id"},"url":{"type":"string","title":"Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"events":{"items":{"type":"string"},"type":"array","title":"Events"},"scope_links":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scope Links","description":"Null means all links, including future ones."},"flavor":{"$ref":"#/components/schemas/WebhookFlavor"},"status":{"$ref":"#/components/schemas/WebhookStatus"},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disabled Reason"},"signing_secret_prefix":{"type":"string","title":"Signing Secret Prefix"},"consecutive_failures":{"type":"integer","title":"Consecutive Failures"},"total_deliveries":{"type":"integer","title":"Total Deliveries"},"total_successes":{"type":"integer","title":"Total Successes"},"last_delivery_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Delivery At"},"last_success_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Success At"},"last_failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Failure Reason"},"created_at":{"type":"integer","title":"Created At"}},"type":"object","required":["id","url","events","flavor","status","signing_secret_prefix","consecutive_failures","total_deliveries","total_successes","created_at"],"title":"WebhookEndpointResponse"},"WebhookEndpointsListResponse":{"properties":{"endpoints":{"items":{"$ref":"#/components/schemas/WebhookEndpointResponse"},"type":"array","title":"Endpoints"}},"type":"object","required":["endpoints"],"title":"WebhookEndpointsListResponse"},"WebhookFlavor":{"type":"string","enum":["raw","discord","slack"],"title":"WebhookFlavor","description":"Presentation of the payload — never a second schema. ``raw`` is the\nversioned contract; other flavors are lossy renderings of it."},"WebhookSecretResponse":{"properties":{"signing_secret":{"type":"string","title":"Signing Secret","description":"The full signing secret, revealed to the endpoint owner."}},"type":"object","required":["signing_secret"],"title":"WebhookSecretResponse"},"WebhookStatus":{"type":"string","enum":["active","paused","disabled"],"title":"WebhookStatus"}},"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"spoo_<key>","description":"API key authentication. Pass your key as: `Bearer spoo_<your_key>`"},"JWTAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT access token from /auth/login. Pass as: `Bearer <jwt_token>`"}}},"tags":[{"name":"URL Shortening","description":"Create new shortened URLs"},{"name":"Me","description":"Per-user preferences and dashboard layouts"},{"name":"Link Management","description":"List, update, and delete your shortened URLs"},{"name":"Statistics","description":"Click analytics and data export"},{"name":"API Keys","description":"Create and manage API keys for programmatic access"},{"name":"Authentication","description":"Login, register, password management, and email verification"},{"name":"OAuth","description":"OAuth provider login, linking, and unlinking"},{"name":"Reports & Contact","description":"Report abusive URLs and contact the site operators"},{"name":"System","description":"Health checks and server metrics"}],"servers":[{"url":"https://spoo.me","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"JWTAuth":[]}]}