{
  "openapi": "3.1.0",
  "info": {
    "title": "MiniURL Agent-First API",
    "version": "1.1.0",
    "description": "MiniURL is built for AI agents and automation. Preferred flow: POST /api/v1/guest/token with no auth, then POST /api/v1/shorten with a guest token. When the user is ready, convert the guest session into a permanent account with POST /api/v1/guest/register and POST /api/v1/guest/verify. Always read the meta object in responses for usage, notices, and upgrade hints.",
    "contact": {
      "name": "MiniURL Support",
      "url": "https://miniurl.com/feedback"
    },
    "termsOfService": "https://miniurl.com/terms"
  },
  "servers": [
    {
      "url": "https://workers.miniurl.com",
      "description": "Production API server"
    }
  ],
  "externalDocs": {
    "description": "LLM and agent quick start",
    "url": "https://miniurl.com/llms.txt"
  },
  "x-agent-guidance": {
    "preferred_first_call": {
      "method": "POST",
      "path": "/api/v1/guest/token"
    },
    "always_read_meta": true
  },
  "paths": {
    "/api/v1/guest/token": {
      "post": {
        "operationId": "createGuestToken",
        "summary": "Create a temporary guest token",
        "tags": ["Guest Onboarding"],
        "security": [],
        "x-token-mode": "no_auth",
        "responses": {
          "200": {
            "description": "Guest token created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GuestTokenResponse"
                },
                "example": {
                  "success": true,
                  "data": {
                    "guest_token": "gt_0123456789abcdef0123456789abcdef0123456789abcdef",
                    "expires_at": "2026-04-04T09:00:00Z",
                    "limits": {
                      "max_links": 5,
                      "max_requests": 30,
                      "expires_in_seconds": 3600
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/guest/register": {
      "post": {
        "operationId": "registerGuestEmail",
        "summary": "Send a verification code to the user email",
        "tags": ["Guest Onboarding"],
        "security": [
          {
            "guestTokenAuth": []
          }
        ],
        "x-token-mode": "gt_only",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterGuestRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification code sent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterGuestResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/guest/verify": {
      "post": {
        "operationId": "verifyGuestEmail",
        "summary": "Verify the code and create a permanent account",
        "tags": ["Guest Onboarding"],
        "security": [
          {
            "guestTokenAuth": []
          }
        ],
        "x-token-mode": "gt_only",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyGuestRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Guest session converted into a permanent account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyGuestResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/account/status": {
      "get": {
        "operationId": "getAccountStatus",
        "summary": "Get account type, quota, and features",
        "tags": ["Account"],
        "security": [
          {
            "guestTokenAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "gt_or_mk",
        "responses": {
          "200": {
            "description": "Account status returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountStatusResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/account/upgrade": {
      "post": {
        "operationId": "upgradeAccount",
        "summary": "Create a short checkout URL for upgrading to Pro",
        "tags": ["Account"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpgradeAccountRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout URL created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpgradeAccountResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/alias/check": {
      "post": {
        "operationId": "checkAliasAvailability",
        "summary": "Check whether an alias is available",
        "description": "Check alias availability on miniurl.com or a specific domain before creating a short link. No authentication required.",
        "tags": ["Aliases"],
        "security": [],
        "x-token-mode": "no_auth",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AliasCheckRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Alias availability returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AliasCheckResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/shorten": {
      "post": {
        "operationId": "createShortLink",
        "summary": "Create a short link",
        "description": "Works with both gt_ and mk_. With gt_, only url is applied; alias, domain, password, expiration, and activated_at are ignored and returned in meta.notices.",
        "tags": ["Links"],
        "security": [
          {
            "guestTokenAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "gt_or_mk",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShortenRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Short link created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateLinkResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/links/bulk": {
      "post": {
        "operationId": "bulkCreateLinks",
        "summary": "Create multiple links in one request",
        "tags": ["Links"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bulk creation processed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkCreateResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/links": {
      "get": {
        "operationId": "listLinks",
        "summary": "List registered-user links",
        "tags": ["Links"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "parameters": [
          {
            "$ref": "#/components/parameters/LimitParam"
          },
          {
            "$ref": "#/components/parameters/OffsetParam"
          },
          {
            "$ref": "#/components/parameters/SearchParam"
          },
          {
            "$ref": "#/components/parameters/DomainFilterParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Links returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LinkListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/links/{alias}": {
      "get": {
        "operationId": "getLink",
        "summary": "Get one link",
        "tags": ["Links"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "parameters": [
          {
            "$ref": "#/components/parameters/AliasParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Link returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateLinkResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "operationId": "updateLink",
        "summary": "Update one link",
        "tags": ["Links"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "parameters": [
          {
            "$ref": "#/components/parameters/AliasParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateLinkRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateLinkResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "operationId": "deleteLink",
        "summary": "Delete one link",
        "tags": ["Links"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "parameters": [
          {
            "$ref": "#/components/parameters/AliasParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Link deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteLinkResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/links/{alias}/stats": {
      "get": {
        "operationId": "getLinkStats",
        "summary": "Get link analytics",
        "description": "Requires mk_. Full analytics require Pro. Free users receive 403 with basic totals in data.",
        "tags": ["Analytics"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "parameters": [
          {
            "$ref": "#/components/parameters/AliasParam"
          },
          {
            "$ref": "#/components/parameters/StatsPeriodParam"
          },
          {
            "$ref": "#/components/parameters/DomainFilterParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Analytics returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LinkStatsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/domains": {
      "get": {
        "operationId": "listDomains",
        "summary": "List available domains for a registered user",
        "tags": ["Domains"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "responses": {
          "200": {
            "description": "Domains returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/v1/tags": {
      "get": {
        "operationId": "listTags",
        "summary": "List account tags",
        "tags": ["Tags"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "responses": {
          "200": {
            "description": "Tags returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TagListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "createTag",
        "summary": "Create a tag",
        "description": "Create a tag for organising links into campaigns or categories. Maximum 20 tags per account.",
        "tags": ["Tags"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTagRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tag created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateTagResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/tags/{tagId}": {
      "delete": {
        "operationId": "deleteTag",
        "summary": "Delete a tag",
        "description": "Delete a tag and remove it from all associated links.",
        "tags": ["Tags"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "parameters": [
          {
            "$ref": "#/components/parameters/TagIdParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Tag deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TagMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/links/{alias}/tags": {
      "get": {
        "operationId": "listLinkTags",
        "summary": "List tags assigned to a link",
        "tags": ["Tags"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "parameters": [
          {
            "$ref": "#/components/parameters/AliasParam"
          },
          {
            "$ref": "#/components/parameters/DomainFilterParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Link tags returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TagListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "operationId": "tagLink",
        "summary": "Assign a tag to a link",
        "tags": ["Tags"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "parameters": [
          {
            "$ref": "#/components/parameters/AliasParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TagAssignmentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tag assigned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TagMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/links/{alias}/tags/{tagId}": {
      "delete": {
        "operationId": "untagLink",
        "summary": "Remove a tag from a link",
        "tags": ["Tags"],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-token-mode": "mk_only",
        "parameters": [
          {
            "$ref": "#/components/parameters/AliasParam"
          },
          {
            "$ref": "#/components/parameters/TagIdParam"
          },
          {
            "$ref": "#/components/parameters/DomainFilterParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Tag removed from link",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TagMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "guestTokenAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Guest token (gt_)",
        "description": "Temporary guest bearer token created by POST /api/v1/guest/token."
      },
      "apiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key (mk_)",
        "description": "Permanent registered-user bearer token returned by POST /api/v1/guest/verify or available in the dashboard."
      }
    },
    "parameters": {
      "AliasParam": {
        "name": "alias",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "TagIdParam": {
        "name": "tagId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 20,
          "minimum": 1,
          "maximum": 100
        }
      },
      "OffsetParam": {
        "name": "offset",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 0,
          "minimum": 0
        }
      },
      "SearchParam": {
        "name": "search",
        "in": "query",
        "schema": {
          "type": "string"
        }
      },
      "DomainFilterParam": {
        "name": "domain",
        "in": "query",
        "schema": {
          "type": "string"
        }
      },
      "StatsPeriodParam": {
        "name": "period",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": ["24H", "7D", "30D", "ALL"],
          "default": "7D"
        }
      }
    },
    "schemas": {
      "Meta": {
        "type": "object",
        "properties": {
          "account_type": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          },
          "usage": {
            "type": "object",
            "additionalProperties": true
          },
          "notices": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "upgrade": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "error": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          },
          "upgrade_url": {
            "type": "string"
          },
          "remaining": {
            "type": ["integer", "null"]
          },
          "limit": {
            "type": ["integer", "null"]
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": ["error"]
      },
      "GuestTokenResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "guest_token": {
                "type": "string"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time"
              },
              "limits": {
                "type": "object",
                "properties": {
                  "max_links": {
                    "type": "integer"
                  },
                  "max_requests": {
                    "type": "integer"
                  },
                  "expires_in_seconds": {
                    "type": "integer"
                  }
                },
                "required": ["max_links", "max_requests", "expires_in_seconds"]
              }
            },
            "required": ["guest_token", "expires_at", "limits"]
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": ["success", "data"]
      },
      "RegisterGuestRequest": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          }
        },
        "required": ["email"]
      },
      "RegisterGuestResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": ["success", "message"]
      },
      "VerifyGuestRequest": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "code": {
            "type": "string"
          }
        },
        "required": ["email", "code"]
      },
      "VerifyGuestResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "api_key": {
                "type": "string"
              },
              "links_claimed": {
                "type": "integer"
              },
              "plan": {
                "type": "string"
              },
              "limits": {
                "type": "object",
                "additionalProperties": true
              }
            },
            "required": ["api_key", "links_claimed", "plan", "limits"]
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": ["success", "data"]
      },
      "AccountStatusResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "account_type": {
                "type": "string"
              },
              "email": {
                "type": ["string", "null"]
              },
              "plan": {
                "type": "object",
                "additionalProperties": true
              },
              "usage": {
                "type": "object",
                "additionalProperties": true
              },
              "features": {
                "type": "object",
                "additionalProperties": true
              }
            },
            "required": ["account_type", "email", "plan", "usage", "features"]
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": ["success", "data"]
      },
      "AliasCheckRequest": {
        "type": "object",
        "properties": {
          "alias": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,64}$"
          },
          "domain": {
            "type": "string"
          }
        },
        "required": ["alias"]
      },
      "AliasCheckResponse": {
        "type": "object",
        "properties": {
          "exists": {
            "type": "boolean"
          }
        },
        "required": ["exists"]
      },
      "ShortenRequest": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "alias": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{3,30}$"
          },
          "domain": {
            "type": "string"
          },
          "password": {
            "type": "string"
          },
          "expiration": {
            "type": "string",
            "format": "date-time"
          },
          "activated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": ["url"]
      },
      "LinkRecord": {
        "type": "object",
        "properties": {
          "short_url": {
            "type": "string"
          },
          "alias": {
            "type": "string"
          },
          "full_url": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "manage_code": {
            "type": ["string", "null"]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "has_password": {
            "type": "boolean"
          },
          "clicks": {
            "type": "integer"
          },
          "last_clicked_at": {
            "type": ["string", "null"],
            "format": "date-time"
          }
        },
        "required": ["short_url", "alias", "full_url", "domain", "created_at"]
      },
      "CreateLinkResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/LinkRecord"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": ["success", "data"]
      },
      "BulkCreateRequest": {
        "type": "object",
        "properties": {
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShortenRequest"
            }
          }
        },
        "required": ["links"]
      },
      "BulkCreateResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "results": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "summary": {
                "type": "object",
                "properties": {
                  "total": {
                    "type": "integer"
                  },
                  "succeeded": {
                    "type": "integer"
                  },
                  "failed": {
                    "type": "integer"
                  }
                },
                "required": ["total", "succeeded", "failed"]
              }
            },
            "required": ["results", "summary"]
          }
        },
        "required": ["success", "data"]
      },
      "LinkListResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "links": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/LinkRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "total": {
                    "type": "integer"
                  },
                  "limit": {
                    "type": "integer"
                  },
                  "offset": {
                    "type": "integer"
                  }
                },
                "required": ["total", "limit", "offset"]
              }
            },
            "required": ["links", "pagination"]
          }
        },
        "required": ["success", "data"]
      },
      "UpdateLinkRequest": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "password": {
            "type": ["string", "null"]
          },
          "expiration": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "activated_at": {
            "type": ["string", "null"],
            "format": "date-time"
          }
        }
      },
      "DeleteLinkResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          }
        },
        "required": ["success", "message"]
      },
      "DomainListResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "domains": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "total": {
                "type": "integer"
              }
            },
            "required": ["domains", "total"]
          }
        },
        "required": ["success", "data"]
      },
      "TagRecord": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "created_at": {
            "type": ["string", "null"],
            "format": "date-time"
          }
        },
        "required": ["id", "name", "color"]
      },
      "TagListResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TagRecord"
            }
          }
        },
        "required": ["success", "tags"]
      },
      "CreateTagRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 30
          },
          "color": {
            "type": "string",
            "enum": ["#6b7280", "#ef4444", "#f97316", "#eab308", "#22c55e", "#06b6d4", "#3b82f6", "#8b5cf6", "#ec4899"]
          }
        },
        "required": ["name"]
      },
      "CreateTagResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "tag": {
            "$ref": "#/components/schemas/TagRecord"
          }
        },
        "required": ["success", "tag"]
      },
      "TagAssignmentRequest": {
        "type": "object",
        "properties": {
          "tagId": {
            "type": "integer",
            "minimum": 1
          },
          "domain": {
            "type": "string"
          }
        },
        "required": ["tagId"]
      },
      "TagMutationResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          }
        },
        "required": ["success"]
      },
      "UpgradeAccountRequest": {
        "type": "object",
        "properties": {
          "interval": {
            "type": "string",
            "enum": ["monthly", "yearly"],
            "default": "monthly"
          }
        }
      },
      "UpgradeAccountResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "checkout_url": {
                "type": "string"
              },
              "interval": {
                "type": "string"
              },
              "price": {
                "type": "string"
              }
            },
            "required": ["checkout_url", "interval", "price"]
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": ["success", "data"]
      },
      "LinkStatsResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "alias": {
                "type": "string"
              },
              "domain": {
                "type": "string"
              },
              "total_clicks": {
                "type": "integer"
              },
              "created_at": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "period": {
                "type": "string"
              },
              "timeseries": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "countries": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "referrers": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "devices": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "browsers": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "os": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "routingStats": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "routingSummary": {
                "type": "object",
                "additionalProperties": true
              }
            },
            "required": ["alias", "domain", "total_clicks"]
          }
        },
        "required": ["success", "data"]
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid input or malformed JSON",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, invalid, expired, or wrong bearer token for this endpoint",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Requires a registered account or a higher plan",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Requested resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Conflict": {
        "description": "Conflict such as alias taken or email already registered",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit, token quota, or plan quota exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Guest Onboarding",
      "description": "Zero-signup flow for AI agents."
    },
    {
      "name": "Account",
      "description": "Account status and upgrade."
    },
    {
      "name": "Links",
      "description": "Create, list, update, and delete links."
    },
    {
      "name": "Aliases",
      "description": "Alias availability checks."
    },
    {
      "name": "Analytics",
      "description": "Link analytics."
    },
    {
      "name": "Domains",
      "description": "Available domains for registered users."
    },
    {
      "name": "Tags",
      "description": "Campaign and category tags for registered users."
    }
  ]
}