api.json

{
    "openapi": "3.0.3",
    "info": {
        "title": "Iriks-IT API",
        "description": "The official API for [Iriks-IT](https://iriks-it.nl). Powering tools, collections, and mischief since Sam knocked the first server off the desk.\n\n> *\"Why did Sam write the API docs? Because Silvia said if he didn't, she'd replace him with a 404 page.\"*\n\nAll authenticated endpoints require a Bearer token obtained via `/auth/login`. Tokens expire after **24 hours** — roughly the time it takes Silvia to forgive you for waking her up.",
        "termsOfService": "https://iriks-it.nl/api-terms/",
        "contact": {
            "email": "devop@iriks-it.nl",
            "name": "Matthijs Iriks",
            "url": "https://iriks-it.nl/"
        },
        "x-logo": {
            "url": "https://iriks-it.nl/logo.png",
            "backgroundColor": "#FFFFFF",
            "altText": "Iriks-IT Logo"
        },
        "version": "1.1.4"
    },
    "externalDocs": {
        "description": "Find out more about Iriks-IT",
        "url": "https://iriks-it.nl"
    },
    "servers": [
        {
            "url": "https://api.iriks-it.nl/v1",
            "description": "Production — where Sam and Silvia live"
        }
    ],
    "security": [
        {
            "BearerToken": []
        }
    ],
    "tags": [
        {
            "name": "account",
            "description": "Purr-fectly secure account management. Sam and Silvia got in, so can you. Email verification required — no exceptions, not even for cats."
        },
        {
            "name": "products",
            "description": "Product catalog API. Sam has already knocked most items off the shelf, but they're all still in the database."
        },
        {
            "name": "hotwheels",
            "description": "Hot Wheels collection tracker. Silvia tried to bat a few under the sofa, but every car is accounted for."
        },
        {
            "name": "tools",
            "description": "Utility endpoints for IP intelligence. Sam sniffs every packet — you get a nice JSON response instead."
        },
        {
            "name": "webhooks",
            "description": "Inbound webhook receivers. Silvia sits on the server and intercepts every status update — nothing gets past her."
        },
        {
            "name": "vrchat",
            "description": "VRChat group utilities. Silvia runs the door policy — Sam checks the ban list. Neither of them tolerates rule-breakers."
        }
    ],
    "paths": {
        "/auth/register": {
            "post": {
                "tags": ["account"],
                "summary": "Register a new account",
                "operationId": "post.account.register",
                "description": "Register your account here. You will receive a verification email — check your inbox, not your spam (or your cat's food bowl). You must verify before you can log in.",
                "security": [],
                "requestBody": {
                    "$ref": "#/components/requestBodies/account.register"
                },
                "responses": {
                    "200": {
                        "description": "Account registered successfully. Check your email to verify.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/response.register"
                                },
                                "example": {
                                    "success": true,
                                    "code": 200,
                                    "data": {
                                        "token": "1|aqWx2RpjFTtYsaOVi3M8df6p54VLKW23W6f48a0",
                                        "name": "Silvia"
                                    },
                                    "message": "User register successfully."
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Email already in use.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/response.error"
                                },
                                "example": {
                                    "success": false,
                                    "code": 409,
                                    "data": "Account already exists, please choose a different one.",
                                    "message": "Registration Error."
                                }
                            }
                        }
                    },
                    "406": {
                        "$ref": "#/components/responses/default406"
                    },
                    "505": {
                        "$ref": "#/components/responses/default505"
                    }
                }
            }
        },
        "/auth/verify": {
            "post": {
                "tags": ["account"],
                "summary": "Verify your account",
                "operationId": "post.account.verify",
                "description": "You found the verification code in your email — now submit it here to unlock API access. Unlike Sam, who needs zero verification to knock things off tables.",
                "security": [],
                "requestBody": {
                    "$ref": "#/components/requestBodies/account.verify"
                },
                "responses": {
                    "200": {
                        "description": "Account verified. You may now log in.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/response.success"
                                },
                                "example": {
                                    "success": true,
                                    "code": 200,
                                    "data": "User verified successfully.",
                                    "message": "Validation Success."
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Verification failed — invalid or expired code.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/response.error"
                                },
                                "example": {
                                    "success": false,
                                    "code": 409,
                                    "data": "Something bad broke, please contact: api@iriks-it.nl",
                                    "message": "Validation Error."
                                }
                            }
                        }
                    },
                    "406": {
                        "$ref": "#/components/responses/default406"
                    },
                    "505": {
                        "$ref": "#/components/responses/default505"
                    }
                }
            }
        },
        "/auth/login": {
            "post": {
                "tags": ["account"],
                "summary": "Log in and obtain a Bearer token",
                "operationId": "post.account.login",
                "description": "Exchange your credentials for an access token and a refresh token. The access token expires after 24 hours — about the same time Sam takes to forgive you for closing the bedroom door. The refresh token is valid for 30 days and can be exchanged at `/auth/refresh` for a fresh pair. You must have verified your account first.",
                "security": [],
                "requestBody": {
                    "$ref": "#/components/requestBodies/account.login"
                },
                "responses": {
                    "200": {
                        "description": "Login successful. Use `token` as `Authorization: Bearer <token>` on all protected endpoints. Store `refresh_token` securely — Sam guards his with his life.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/response.login"
                                },
                                "example": {
                                    "success": true,
                                    "code": 200,
                                    "data": {
                                        "token": "3|qF30ZVY2xW1OXJieMLXhUXZowwgVGVbm6F3kSoT714e04dec",
                                        "expire": "2026-05-08 10:00:00",
                                        "refresh_token": "4|rG41AWZ3yX2PYKjfNMYiVYApxxhWHWcn7G4lTpU825f15efd",
                                        "refresh_expire": "2026-06-06 10:00:00",
                                        "name": "Silvia"
                                    },
                                    "message": "User login successfully."
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Account not verified yet — Silvia is still screening you.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/response.error"
                                },
                                "example": {
                                    "success": false,
                                    "code": 403,
                                    "data": "Account hasn't been verified yet, please verify this first!",
                                    "message": "Unauthorised"
                                }
                            }
                        }
                    },
                    "406": {
                        "$ref": "#/components/responses/default406"
                    },
                    "505": {
                        "$ref": "#/components/responses/default505"
                    }
                }
            }
        },
        "/auth/refresh": {
            "post": {
                "tags": ["account"],
                "summary": "Refresh your access token",
                "operationId": "post.account.refresh",
                "description": "Exchange a valid refresh token for a fresh access token + refresh token pair. The old refresh token is immediately invalidated — single-use, like Sam's patience when his food bowl is empty.\n\nSend the refresh token (not the access token) in the `Authorization: Bearer` header. Using an access token here will be rejected with 403.",
                "security": [
                    { "BearerToken": [] }
                ],
                "responses": {
                    "200": {
                        "description": "New token pair issued. The old refresh token is now dead — Silvia shredded it.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/response.login"
                                },
                                "example": {
                                    "success": true,
                                    "code": 200,
                                    "data": {
                                        "token": "5|sH52BXA4zY3QZLkgONZjWZBqyyiXIXdo8H5mUqV936g26fge",
                                        "expire": "2026-05-09 10:00:00",
                                        "refresh_token": "6|tI63CYB5aZ4RAMlhPOAkXACrzzjYJYep9I6nVrW047h37ghf",
                                        "refresh_expire": "2026-06-07 10:00:00",
                                        "name": "Silvia"
                                    },
                                    "message": "Token refreshed successfully."
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The refresh token was not found — it may have already been used or expired. Sam says no.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 401,
                                    "message": "Unauthorised"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The token provided does not have the `token-refresh` ability. You likely sent an access token instead of a refresh token — Silvia can tell the difference.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 403,
                                    "message": "Invalid token type."
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            }
        },
        "/products": {
            "get": {
                "tags": ["products"],
                "summary": "List all products",
                "operationId": "get.products.index",
                "description": "Returns all products. Sam has inspected every single one and found most of them interesting enough to sit on.",
                "responses": {
                    "200": {
                        "description": "Products retrieved successfully.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": {
                                            "type": "array",
                                            "items": { "$ref": "#/components/schemas/product" }
                                        },
                                        "message": { "type": "string", "example": "Products retrieved successfully." }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "code": 200,
                                    "data": [
                                        {
                                            "id": 1,
                                            "name": "Premium Cat Food — Sam's Choice",
                                            "detail": "Sam rated this 10/10. He ate the whole bag in one sitting and then knocked the empty bag off the counter.",
                                            "created_at": "19/04/2026",
                                            "updated_at": "19/04/2026"
                                        },
                                        {
                                            "id": 2,
                                            "name": "Interactive Laser Pointer — Silvia Edition",
                                            "detail": "Silvia has been chasing this dot since 2023. She has yet to catch it. We consider this a feature.",
                                            "created_at": "19/04/2026",
                                            "updated_at": "19/04/2026"
                                        }
                                    ],
                                    "message": "Products retrieved successfully."
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            },
            "post": {
                "tags": ["products"],
                "summary": "Create a product",
                "operationId": "post.products.store",
                "description": "Create a new product. Sam will immediately investigate it and determine whether it belongs on the floor.",
                "requestBody": {
                    "$ref": "#/components/requestBodies/product.store"
                },
                "responses": {
                    "200": {
                        "description": "Product created successfully.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": { "$ref": "#/components/schemas/product" },
                                        "message": { "type": "string", "example": "Product created successfully." }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "code": 200,
                                    "data": {
                                        "id": 3,
                                        "name": "Catnip Deluxe",
                                        "detail": "Silvia's weakness. Sam pretends he doesn't care, then steals it at 3 AM.",
                                        "created_at": "19/04/2026",
                                        "updated_at": "19/04/2026"
                                    },
                                    "message": "Product created successfully."
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "406": {
                        "$ref": "#/components/responses/default406"
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            }
        },
        "/products/{id}": {
            "get": {
                "tags": ["products"],
                "summary": "Get a product",
                "operationId": "get.products.show",
                "description": "Retrieve a single product by ID. If Sam knocked it off the shelf, it still exists in the database.",
                "parameters": [
                    { "$ref": "#/components/parameters/id" }
                ],
                "responses": {
                    "200": {
                        "description": "Product retrieved successfully.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": { "$ref": "#/components/schemas/product" },
                                        "message": { "type": "string", "example": "Product retrieved successfully." }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "404": {
                        "$ref": "#/components/responses/default404"
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            },
            "put": {
                "tags": ["products"],
                "summary": "Update a product",
                "operationId": "put.products.update",
                "description": "Update an existing product. Silvia reviewed the change and gave it a slow blink of approval.",
                "parameters": [
                    { "$ref": "#/components/parameters/id" }
                ],
                "requestBody": {
                    "$ref": "#/components/requestBodies/product.store"
                },
                "responses": {
                    "200": {
                        "description": "Product updated successfully.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": { "$ref": "#/components/schemas/product" },
                                        "message": { "type": "string", "example": "Product updated successfully." }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "404": {
                        "$ref": "#/components/responses/default404"
                    },
                    "406": {
                        "$ref": "#/components/responses/default406"
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            },
            "delete": {
                "tags": ["products"],
                "summary": "Delete a product",
                "operationId": "delete.products.destroy",
                "description": "Permanently delete a product. Unlike Sam's attitude when you're five minutes late with breakfast, this action cannot be taken back.",
                "parameters": [
                    { "$ref": "#/components/parameters/id" }
                ],
                "responses": {
                    "200": {
                        "description": "Product deleted successfully.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": { "type": "array", "items": {}, "example": [] },
                                        "message": { "type": "string", "example": "Product deleted successfully." }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "404": {
                        "$ref": "#/components/responses/default404"
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            }
        },
        "/hotwheels": {
            "get": {
                "tags": ["hotwheels"],
                "summary": "List all Hot Wheels",
                "operationId": "get.hotwheels.index",
                "description": "Returns the full Hot Wheels collection. Silvia once batted a 1970 Dodge Charger under the sofa. It was recovered. It is in this list.",
                "responses": {
                    "200": {
                        "description": "Hot Wheels retrieved successfully.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": {
                                            "type": "array",
                                            "items": { "$ref": "#/components/schemas/hotwheels" }
                                        },
                                        "message": { "type": "string", "example": "Hot Wheels retrieved successfully." }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "code": 200,
                                    "data": [
                                        {
                                            "id": 1,
                                            "user": 1,
                                            "condition": "Mint",
                                            "in_packing": true,
                                            "toy_num": "HW24-001",
                                            "col_num": "001/250",
                                            "model": "Paw-rsche 911 GT3",
                                            "series": "Sam's Garage",
                                            "series_num": "1/10",
                                            "year": 2024,
                                            "photo_url": "https://example.com/hw/paw-rsche-911.jpg",
                                            "detail": "Sam sat on the box once but it survived. Purr-fect condition.",
                                            "created_at": "19/04/2026",
                                            "updated_at": "19/04/2026"
                                        },
                                        {
                                            "id": 2,
                                            "user": 1,
                                            "condition": "Good",
                                            "in_packing": false,
                                            "toy_num": "HW24-002",
                                            "col_num": "002/250",
                                            "model": "Meow-stang GT500",
                                            "series": "Silvia's Picks",
                                            "series_num": "2/10",
                                            "year": 2024,
                                            "photo_url": "https://example.com/hw/meow-stang.jpg",
                                            "detail": "Silvia batted it off the shelf exactly once. We consider it loved.",
                                            "created_at": "19/04/2026",
                                            "updated_at": "19/04/2026"
                                        }
                                    ],
                                    "message": "Hot Wheels retrieved successfully."
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            },
            "post": {
                "tags": ["hotwheels"],
                "summary": "Add a Hot Wheels car",
                "operationId": "post.hotwheels.store",
                "description": "Add a new car to the collection. Sam will judge its aerodynamics by sniffing it.",
                "requestBody": {
                    "$ref": "#/components/requestBodies/hotwheels.store"
                },
                "responses": {
                    "200": {
                        "description": "Car added to the collection successfully.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": { "$ref": "#/components/schemas/hotwheels" },
                                        "message": { "type": "string", "example": "Product created successfully." }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "406": {
                        "$ref": "#/components/responses/default406"
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            }
        },
        "/hotwheels/{id}": {
            "get": {
                "tags": ["hotwheels"],
                "summary": "Get a Hot Wheels car",
                "operationId": "get.hotwheels.show",
                "description": "Get a specific car from the collection. Even if Sam licked it, it's still in the database.",
                "parameters": [
                    { "$ref": "#/components/parameters/id" }
                ],
                "responses": {
                    "200": {
                        "description": "Car retrieved successfully.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": { "$ref": "#/components/schemas/hotwheels" },
                                        "message": { "type": "string", "example": "Product retrieved successfully." }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "404": {
                        "$ref": "#/components/responses/default404"
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            },
            "put": {
                "tags": ["hotwheels"],
                "summary": "Update a Hot Wheels car",
                "operationId": "put.hotwheels.update",
                "description": "Update a car's name or detail. Silvia approved this endpoint with a slow blink.",
                "parameters": [
                    { "$ref": "#/components/parameters/id" }
                ],
                "requestBody": {
                    "$ref": "#/components/requestBodies/hotwheels.update"
                },
                "responses": {
                    "200": {
                        "description": "Car updated successfully.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": { "$ref": "#/components/schemas/hotwheels" },
                                        "message": { "type": "string", "example": "Product updated successfully." }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "404": {
                        "$ref": "#/components/responses/default404"
                    },
                    "406": {
                        "$ref": "#/components/responses/default406"
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            },
            "delete": {
                "tags": ["hotwheels"],
                "summary": "Delete a Hot Wheels car",
                "operationId": "delete.hotwheels.destroy",
                "description": "Remove a car from the collection. More permanent than Silvia hiding it under the fridge.",
                "parameters": [
                    { "$ref": "#/components/parameters/id" }
                ],
                "responses": {
                    "200": {
                        "description": "Car deleted from the collection.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": { "type": "array", "items": {}, "example": [] },
                                        "message": { "type": "string", "example": "Hot Wheels deleted successfully." }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "404": {
                        "$ref": "#/components/responses/default404"
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            }
        },
        "/tools/ip/{ip}": {
            "get": {
                "tags": ["tools"],
                "summary": "Look up an IP address",
                "operationId": "get.tools.ip.show",
                "description": "Returns geolocation, ASN, proxy detection, and AbuseIPDB threat intelligence for an IPv4 or IPv6 address. Sam sniffs every packet — you get structured JSON.\n\nRequires the `ip.lookup` permission scope on your token.\n\n**Caching:** AbuseIPDB results are cached for 14 days per IP to stay well within rate limits. Fresh data is fetched automatically when the cache expires.",
                "parameters": [
                    {
                        "name": "ip",
                        "in": "path",
                        "required": true,
                        "description": "The IPv4 or IPv6 address to look up. Sam's current IP is classified.",
                        "schema": {
                            "type": "string",
                            "examples": ["118.25.6.39", "2001:db8::1", "1.1.1.1"]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "IP data retrieved successfully. Sam sniffed it and found no suspicious treats.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": { "$ref": "#/components/schemas/ip.lookup" },
                                        "message": { "type": "string", "example": "IP data retrieved successfully." }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "code": 200,
                                    "data": {
                                        "ip": "118.25.6.39",
                                        "location": {
                                            "country_code": "CN",
                                            "country_name": "China",
                                            "region_name": "Guangdong",
                                            "city_name": "Shenzhen",
                                            "latitude": 22.5431,
                                            "longitude": 114.0579,
                                            "zip_code": "518000",
                                            "time_zone": "+08:00"
                                        },
                                        "country": {
                                            "alpha3_code": "CHN",
                                            "numeric_code": "156",
                                            "capital": "Beijing",
                                            "currency_code": "CNY",
                                            "currency_name": "Yuan Renminbi",
                                            "currency_symbol": "¥",
                                            "cctld": ".cn",
                                            "idd_code": "86",
                                            "population": 1411750000,
                                            "total_area": 9596960
                                        },
                                        "continent": {
                                            "code": "AS",
                                            "name": "Asia"
                                        },
                                        "timezone": {
                                            "olson": "Asia/Shanghai",
                                            "abbreviation": "CST",
                                            "dst_start": null,
                                            "dst_end": null
                                        },
                                        "metro": null,
                                        "asn": {
                                            "asn": "AS45090",
                                            "organization": "Tencent Cloud Computing (Beijing) Co. Ltd",
                                            "network": "118.25.0.0/16"
                                        },
                                        "threat": {
                                            "score": 75,
                                            "is_proxy": true,
                                            "is_vpn": false,
                                            "is_threat": true,
                                            "reasons": [
                                                "Hosting / data center IP",
                                                "Threat category: SPAM",
                                                "High-risk country: China"
                                            ],
                                            "total_reports": 42,
                                            "last_reported_at": "2024-01-15T10:00:00+00:00",
                                            "checked_at": "2026-04-19T14:00:00+00:00",
                                            "reports": [
                                                {
                                                    "reported_at": "2024-01-15T10:00:00+00:00",
                                                    "categories": [18, 22],
                                                    "comment": "Sam detected suspicious SSH traffic from this IP at 3 AM. He woke up the admin by sitting on the keyboard.",
                                                    "reporter_country_code": "NL",
                                                    "reporter_country_name": "Netherlands"
                                                },
                                                {
                                                    "reported_at": "2024-01-10T08:30:00+00:00",
                                                    "categories": [22],
                                                    "comment": "Silvia noticed this IP sniffing her ports. She hissed at it and reported it immediately.",
                                                    "reporter_country_code": "NL",
                                                    "reporter_country_name": "Netherlands"
                                                }
                                            ]
                                        }
                                    },
                                    "message": "IP data retrieved successfully."
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "403": {
                        "description": "Missing `ip.lookup` permission scope on your token.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 403,
                                    "data": "",
                                    "message": "You do not have permission to perform IP lookups."
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    },
                    "422": {
                        "description": "The provided value is not a valid IP address. Even Sam knows `meow` is not an IP.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 422,
                                    "data": "",
                                    "message": "The provided value is not a valid IP address."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/vrchat/ban-appeal": {
            "post": {
                "tags": ["vrchat"],
                "summary": "Submit a ban appeal",
                "operationId": "post.vrchat.ban-appeal",
                "description": "Submit a ban appeal for a VRChat group ban. Requires a valid Bearer token with the `vrchat.banappeal` permission scope.\n\n**Rate limit:** One appeal per IP address per 14 days. Silvia keeps count. Your IP address is recorded with the appeal.\n\n> *\"Sam submitted an appeal for knocking the server over. His reason: 'it looked unstable.' It was not accepted.\"*",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": ["vrchat_user_id", "name", "email", "reason"],
                                "properties": {
                                    "vrchat_user_id": {
                                        "type": "string",
                                        "description": "Your VRChat user ID. Must match `usr_<uuid>` format.",
                                        "example": "usr_00000000-0000-0000-0000-000000000001"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Your VRChat display name.",
                                        "example": "Silvia"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "description": "Your contact email address.",
                                        "example": "silvia@iriks-it.nl"
                                    },
                                    "reason": {
                                        "type": "string",
                                        "maxLength": 5000,
                                        "description": "Why you believe the ban should be lifted. Sam reads every word.",
                                        "example": "I knocked that toy off the shelf on purpose, not by accident. I deserve to come back."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Appeal submitted. Silvia will review it when she wakes up from her nap.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "submitted": { "type": "boolean", "example": true }
                                            }
                                        },
                                        "message": { "type": "string", "example": "Your ban appeal has been submitted." }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "code": 200,
                                    "data": { "submitted": true },
                                    "message": "Your ban appeal has been submitted."
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "403": {
                        "description": "Missing `vrchat.banappeal` permission scope on your token.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 403,
                                    "data": "",
                                    "message": "You do not have permission to submit VRChat ban appeals."
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed. Check your field values — Sam flagged them.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 422,
                                    "message": "Validation Error.",
                                    "data": {
                                        "vrchat_user_id": ["The vrchat user id field format is invalid."],
                                        "email": ["The email field must be a valid email address."]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "An appeal from this IP was already submitted in the last 14 days. Silvia is still deliberating.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 429,
                                    "message": "A ban appeal from this IP address was already submitted recently. Please wait 14 days before trying again."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/vrchat/ban-lookup/{userId}": {
            "get": {
                "tags": ["vrchat"],
                "summary": "Look up whether a VRChat user is banned",
                "operationId": "get.vrchat.ban-lookup",
                "description": "Checks the group's audit log history to determine whether a given VRChat user ID has ever been banned. Returns `banned: false` if no ban event is found. If banned, returns the actor, timestamp, description, and any operator notes.\n\nRequires the `vrchat.banlookup` permission scope on your token.\n\n> *\"Sam sat on the ban list once and accidentally approved it. We added a notes field so we could write 'Sam did it again'.\"*",
                "parameters": [
                    {
                        "name": "userId",
                        "in": "path",
                        "required": true,
                        "description": "The VRChat user ID to look up. Must match the format `usr_<uuid>`. Silvia refuses to check anything else.",
                        "schema": {
                            "type": "string",
                            "example": "usr_00000000-0000-0000-0000-000000000001"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lookup completed. `banned: false` means the user is clean — for now. Silvia is watching.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "data": {
                                            "oneOf": [
                                                {
                                                    "title": "Not banned",
                                                    "type": "object",
                                                    "properties": {
                                                        "banned": { "type": "boolean", "example": false }
                                                    }
                                                },
                                                {
                                                    "title": "Banned",
                                                    "type": "object",
                                                    "properties": {
                                                        "banned": { "type": "boolean", "example": true },
                                                        "banned_by": { "type": "string", "nullable": true, "example": "Silvia" },
                                                        "banned_at": { "type": "string", "format": "date-time", "example": "2026-04-28T13:37:00.000000Z" },
                                                        "reason": { "type": "string", "nullable": true, "example": "Knocked every cat toy out of the group instance." },
                                                        "notes": { "type": "string", "nullable": true, "example": "Third offence. Sam reviewed the footage. Unanimous decision." }
                                                    }
                                                }
                                            ]
                                        },
                                        "message": { "type": "string" }
                                    }
                                },
                                "examples": {
                                    "not_banned": {
                                        "summary": "User is not banned",
                                        "value": {
                                            "success": true,
                                            "code": 200,
                                            "data": { "banned": false },
                                            "message": "User is not banned."
                                        }
                                    },
                                    "banned": {
                                        "summary": "User is banned",
                                        "value": {
                                            "success": true,
                                            "code": 200,
                                            "data": {
                                                "banned": true,
                                                "banned_by": "Silvia",
                                                "banned_at": "2026-04-28T13:37:00.000000Z",
                                                "reason": "Knocked every cat toy out of the group instance.",
                                                "notes": "Third offence. Sam reviewed the footage. Unanimous decision."
                                            },
                                            "message": "User is banned."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "403": {
                        "description": "Missing `vrchat.banlookup` permission scope on your token. Sam says no.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 403,
                                    "data": "",
                                    "message": "You do not have permission to perform VRChat ban lookups."
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The provided value is not a valid VRChat user ID. Silvia only accepts `usr_<uuid>` format — she has standards.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 422,
                                    "data": "",
                                    "message": "The provided value is not a valid VRChat user ID."
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            }
        },
        "/vrchat/lookup/{userId}": {
            "get": {
                "tags": ["vrchat"],
                "summary": "Look up a VRChat user by ID",
                "operationId": "get.vrchat.lookup",
                "description": "Fetches public profile information for a VRChat user directly from the VRChat API. Returns a curated set of public fields — location, friend status, login timestamps, and other private fields are intentionally omitted.\n\nRequires the `vrchat.lookup` permission scope on your token.\n\n> *\"Silvia personally reviews every lookup. Sam just checks if it's his own ID so he can update his bio to 'not guilty'.\"*",
                "parameters": [
                    {
                        "name": "userId",
                        "in": "path",
                        "required": true,
                        "description": "The VRChat user ID to look up. Must match the format `usr_<uuid>`. Silvia only accepts valid IDs — she has standards.",
                        "schema": {
                            "type": "string",
                            "example": "usr_00000000-0000-0000-0000-000000000001"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "User found. Silvia approves. Sam is jealous of the bio.",
                        "headers": {
                            "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                            "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                            "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": { "type": "boolean", "example": true },
                                        "code": { "type": "integer", "example": 200 },
                                        "message": { "type": "string", "example": "VRChat user retrieved." },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "user_id": { "type": "string", "example": "usr_00000000-0000-0000-0000-000000000001" },
                                                "display_name": { "type": "string", "example": "Silvia" },
                                                "pronouns": { "type": "string", "nullable": true, "example": "she/her" },
                                                "bio": { "type": "string", "nullable": true, "example": "Professional server knocker. No regrets." },
                                                "bio_links": { "type": "array", "items": { "type": "string" }, "example": ["https://silvia.cat"] },
                                                "status": { "type": "string", "nullable": true, "example": "active", "description": "VRChat status: `active`, `join me`, `ask me`, or `busy`." },
                                                "status_description": { "type": "string", "nullable": true, "example": "Knocking things off shelves" },
                                                "state": { "type": "string", "nullable": true, "example": "online", "description": "Presence state: `online`, `active`, or `offline`." },
                                                "last_platform": { "type": "string", "nullable": true, "example": "standalonewindows", "description": "Last platform seen on: `standalonewindows`, `android`, `ios`, etc." },
                                                "date_joined": { "type": "string", "format": "date", "nullable": true, "example": "2020-01-01" },
                                                "developer_type": { "type": "string", "nullable": true, "example": "none", "description": "VRChat developer badge level: `none`, `trusted`, `internal`, or `moderator`." },
                                                "tags": { "type": "array", "items": { "type": "string" }, "example": ["system_trust_known"] },
                                                "avatar_thumbnail_url": { "type": "string", "nullable": true, "example": "https://api.vrchat.cloud/api/1/image/thumbnail.png" },
                                                "profile_pic_override": { "type": "string", "nullable": true, "example": "" },
                                                "profile_pic_override_thumbnail": { "type": "string", "nullable": true, "example": "" },
                                                "user_icon": { "type": "string", "nullable": true, "example": "" }
                                            }
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "code": 200,
                                    "data": {
                                        "user_id": "usr_00000000-0000-0000-0000-000000000001",
                                        "display_name": "Silvia",
                                        "pronouns": "she/her",
                                        "bio": "Professional server knocker. No regrets.",
                                        "bio_links": ["https://silvia.cat"],
                                        "status": "active",
                                        "status_description": "Knocking things off shelves",
                                        "state": "online",
                                        "last_platform": "standalonewindows",
                                        "date_joined": "2020-01-01",
                                        "developer_type": "none",
                                        "tags": ["system_trust_known"],
                                        "avatar_thumbnail_url": "https://api.vrchat.cloud/api/1/image/thumbnail.png",
                                        "profile_pic_override": "",
                                        "profile_pic_override_thumbnail": "",
                                        "user_icon": ""
                                    },
                                    "message": "VRChat user retrieved."
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/default401"
                    },
                    "403": {
                        "description": "Missing `vrchat.lookup` permission scope on your token. Silvia personally enforces this.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 403,
                                    "data": "",
                                    "message": "You do not have permission to perform VRChat user lookups."
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "VRChat user not found or the VRChat API returned no data. Sam checked twice — they're not there.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 404,
                                    "data": "",
                                    "message": "VRChat user not found."
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The provided value is not a valid VRChat user ID. Must match `usr_<uuid>`. Silvia only accepts valid IDs — she has standards.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 422,
                                    "data": "",
                                    "message": "The provided value is not a valid VRChat user ID."
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/default429"
                    }
                }
            }
        },
        "/webhooks/statuspage/{code}": {
            "post": {
                "tags": ["webhooks"],
                "summary": "Receive an Atlassian Statuspage webhook",
                "operationId": "post.webhooks.statuspage",
                "description": "Receives inbound incident or component-update payloads from an Atlassian Statuspage subscription. The `{code}` path segment identifies the registered source — Silvia checks it against a list of known sources and meows loudly if it is not recognised.\n\nNew incident updates are stored and forwarded to configured notification channels (Discord, Telegram). Duplicate deliveries are safely ignored — Silvia never processes the same update twice.\n\nThis endpoint requires no authentication token; access is gated solely by the source `{code}`.",
                "security": [],
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "description": "The unique source code registered for this Statuspage subscription. Sam guards the list — unknown codes get a 404.",
                        "schema": {
                            "type": "string",
                            "example": "vrchat"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "description": "Atlassian Statuspage webhook payload. Must contain either an `incident` or a `component_update` key.",
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "meta": {
                                        "type": "object",
                                        "properties": {
                                            "unsubscribe": { "type": "string", "format": "uri" },
                                            "documentation": { "type": "string", "format": "uri" }
                                        }
                                    },
                                    "page": {
                                        "type": "object",
                                        "properties": {
                                            "id": { "type": "string", "example": "kctbh9vrtdwd" },
                                            "status_indicator": { "type": "string", "example": "critical" },
                                            "status_description": { "type": "string", "example": "Major System Outage" }
                                        }
                                    },
                                    "incident": {
                                        "type": "object",
                                        "description": "Present for incident payloads.",
                                        "properties": {
                                            "id": { "type": "string", "example": "lbkhbwn21v5q" },
                                            "name": { "type": "string", "example": "Sam knocked the auth server off the desk" },
                                            "status": { "type": "string", "example": "investigating" },
                                            "impact": { "type": "string", "example": "critical" },
                                            "shortlink": { "type": "string", "format": "uri", "example": "https://stspg.io/abc123" },
                                            "resolved_at": { "type": "string", "format": "date-time", "nullable": true },
                                            "incident_updates": {
                                                "type": "array",
                                                "description": "Newest first. The last item is always the initial report.",
                                                "items": {
                                                    "type": "object",
                                                    "properties": {
                                                        "id": { "type": "string" },
                                                        "status": { "type": "string" },
                                                        "body": { "type": "string" },
                                                        "display_at": { "type": "string", "format": "date-time" }
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "component_update": {
                                        "type": "object",
                                        "description": "Present for component-update payloads.",
                                        "properties": {
                                            "id": { "type": "string", "example": "k7730b5v92bv" },
                                            "component_id": { "type": "string", "example": "rb5wq1dczvbm" },
                                            "old_status": { "type": "string", "example": "major_outage" },
                                            "new_status": { "type": "string", "example": "operational" }
                                        }
                                    },
                                    "component": {
                                        "type": "object",
                                        "description": "Present alongside component_update.",
                                        "properties": {
                                            "id": { "type": "string" },
                                            "name": { "type": "string", "example": "Authentication Service" },
                                            "status": { "type": "string", "example": "operational" }
                                        }
                                    }
                                }
                            },
                            "examples": {
                                "incident": {
                                    "summary": "Incident update — Silvia spotted an outage",
                                    "value": {
                                        "meta": { "unsubscribe": "https://status.vrchat.com/?unsubscribe=abc" },
                                        "page": { "id": "kctbh9vrtdwd", "status_indicator": "critical", "status_description": "Major System Outage" },
                                        "incident": {
                                            "id": "lbkhbwn21v5q",
                                            "name": "Sam knocked the auth server off the desk",
                                            "status": "investigating",
                                            "impact": "critical",
                                            "shortlink": "https://stspg.io/abc123",
                                            "resolved_at": null,
                                            "incident_updates": [
                                                { "id": "qbbsfhy5s9kk", "status": "investigating", "body": "We are investigating the issue — Sam is being gently removed from the server room.", "display_at": "2026-04-27T10:00:00Z" }
                                            ]
                                        }
                                    }
                                },
                                "component": {
                                    "summary": "Component update — Silvia approves",
                                    "value": {
                                        "meta": { "unsubscribe": "https://status.vrchat.com/?unsubscribe=abc" },
                                        "page": { "id": "kctbh9vrtdwd", "status_indicator": "major", "status_description": "Partial System Outage" },
                                        "component_update": { "id": "k7730b5v92bv", "component_id": "rb5wq1dczvbm", "old_status": "major_outage", "new_status": "operational" },
                                        "component": { "id": "rb5wq1dczvbm", "name": "Authentication Service", "status": "operational" }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Webhook received and queued for processing. Sam will process it shortly.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.success" },
                                "example": {
                                    "success": true,
                                    "code": 200,
                                    "data": [],
                                    "message": "Webhook received."
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown source code. Silvia does not recognise this visitor.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/response.error" },
                                "example": {
                                    "success": false,
                                    "code": 404,
                                    "message": "Unknown webhook code."
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "parameters": {
            "id": {
                "name": "id",
                "in": "path",
                "required": true,
                "description": "The resource ID. Sam starts counting from 1.",
                "schema": {
                    "type": "integer",
                    "format": "int64",
                    "example": 1
                }
            }
        },
        "schemas": {
            "response.success": {
                "type": "object",
                "properties": {
                    "success": { "type": "boolean", "example": true },
                    "code": { "type": "integer", "format": "int32", "example": 200 },
                    "data": {},
                    "message": { "type": "string" }
                }
            },
            "response.error": {
                "type": "object",
                "properties": {
                    "success": { "type": "boolean", "example": false },
                    "code": { "type": "integer", "format": "int32" },
                    "data": {},
                    "message": { "type": "string" }
                }
            },
            "response.register": {
                "type": "object",
                "properties": {
                    "success": { "type": "boolean", "example": true },
                    "code": { "type": "integer", "format": "int32", "example": 200 },
                    "data": {
                        "type": "object",
                        "properties": {
                            "token": { "type": "string", "example": "1|aqWx2RpjFTtYsaOVi3M8df6p54VLKW23W6f48a0" },
                            "name": { "type": "string", "example": "Silvia" }
                        }
                    },
                    "message": { "type": "string", "example": "User register successfully." }
                }
            },
            "response.login": {
                "type": "object",
                "properties": {
                    "success": { "type": "boolean", "example": true },
                    "code": { "type": "integer", "format": "int32", "example": 200 },
                    "data": {
                        "type": "object",
                        "properties": {
                            "token": { "type": "string", "description": "Short-lived access token. Valid for 24 hours. Use this for all API calls.", "example": "3|qF30ZVY2xW1OXJieMLXhUXZowwgVGVbm6F3kSoT714e04dec" },
                            "expire": { "type": "string", "format": "date-time", "description": "UTC expiry of the access token.", "example": "2026-05-08 10:00:00" },
                            "refresh_token": { "type": "string", "description": "Long-lived refresh token. Valid for 30 days. Single-use — exchange it at `/auth/refresh` for a new pair. Store securely; Sam treats his like a state secret.", "example": "4|rG41AWZ3yX2PYKjfNMYiVYApxxhWHWcn7G4lTpU825f15efd" },
                            "refresh_expire": { "type": "string", "format": "date-time", "description": "UTC expiry of the refresh token.", "example": "2026-06-06 10:00:00" },
                            "name": { "type": "string", "example": "Silvia" }
                        }
                    },
                    "message": { "type": "string", "example": "User login successfully." }
                }
            },
            "account.register": {
                "required": ["name", "email", "password", "c_password"],
                "type": "object",
                "properties": {
                    "name": { "type": "string", "example": "Silvia" },
                    "email": { "type": "string", "format": "email", "example": "silvia@iriks-it.nl" },
                    "password": { "type": "string", "format": "password", "example": "g!v3m3f00dn0w!" },
                    "c_password": { "type": "string", "format": "password", "example": "g!v3m3f00dn0w!" }
                }
            },
            "account.verify": {
                "required": ["email", "code"],
                "type": "object",
                "properties": {
                    "email": { "type": "string", "format": "email", "example": "silvia@iriks-it.nl" },
                    "code": { "type": "string", "example": "1234-ABCD-5678-EDFG-1337" }
                }
            },
            "account.login": {
                "required": ["email", "password"],
                "type": "object",
                "properties": {
                    "email": { "type": "string", "format": "email", "example": "silvia@iriks-it.nl" },
                    "password": { "type": "string", "format": "password", "example": "g!v3m3f00dn0w!" }
                }
            },
            "product": {
                "type": "object",
                "properties": {
                    "id": { "type": "integer", "format": "int64", "example": 1 },
                    "name": { "type": "string", "example": "Premium Cat Food — Sam's Choice" },
                    "detail": { "type": "string", "example": "Sam rated this 10/10. He ate the whole bag and then knocked the empty bag off the counter." },
                    "created_at": { "type": "string", "example": "19/04/2026" },
                    "updated_at": { "type": "string", "example": "19/04/2026" }
                }
            },
            "product.input": {
                "required": ["name", "detail"],
                "type": "object",
                "properties": {
                    "name": { "type": "string", "example": "Catnip Deluxe" },
                    "detail": { "type": "string", "example": "Silvia's weakness. Sam pretends he doesn't care, then steals it at 3 AM." }
                }
            },
            "hotwheels": {
                "type": "object",
                "properties": {
                    "id": { "type": "integer", "format": "int64", "example": 1 },
                    "user": { "type": "integer", "description": "User ID of the owner", "example": 1 },
                    "condition": { "type": "string", "description": "Physical condition of the car", "example": "Mint" },
                    "in_packing": { "type": "boolean", "description": "Whether the car is still in its original packaging", "example": true },
                    "toy_num": { "type": "string", "description": "Hot Wheels toy number", "example": "HW24-001" },
                    "col_num": { "type": "string", "description": "Collection number", "example": "001/250" },
                    "model": { "type": "string", "description": "Car model name", "example": "Paw-rsche 911 GT3" },
                    "series": { "type": "string", "description": "Hot Wheels series name", "example": "Sam's Garage" },
                    "series_num": { "type": "string", "description": "Position within the series", "example": "1/10" },
                    "year": { "type": "integer", "description": "Release year", "example": 2024 },
                    "photo_url": { "type": "string", "format": "uri", "description": "URL to the car's photo", "example": "https://example.com/hw/paw-rsche-911.jpg" },
                    "detail": { "type": "string", "nullable": true, "example": "Sam sat on the box once but it survived. Purr-fect condition." },
                    "created_at": { "type": "string", "example": "19/04/2026" },
                    "updated_at": { "type": "string", "example": "19/04/2026" }
                }
            },
            "hotwheels.input": {
                "required": ["user", "condition", "in_packing", "toy_num", "col_num", "model", "series", "series_num", "year", "photo_url"],
                "type": "object",
                "properties": {
                    "user": { "type": "integer", "description": "User ID of the owner", "example": 1 },
                    "condition": { "type": "string", "description": "Physical condition: Mint, Good, Fair, Poor", "example": "Mint" },
                    "in_packing": { "type": "boolean", "description": "Is the car still in original packaging?", "example": true },
                    "toy_num": { "type": "string", "example": "HW24-001" },
                    "col_num": { "type": "string", "example": "001/250" },
                    "model": { "type": "string", "example": "Paw-rsche 911 GT3" },
                    "series": { "type": "string", "example": "Sam's Garage" },
                    "series_num": { "type": "string", "example": "1/10" },
                    "year": { "type": "integer", "example": 2024 },
                    "photo_url": { "type": "string", "format": "uri", "example": "https://example.com/hw/paw-rsche-911.jpg" },
                    "detail": { "type": "string", "nullable": true, "example": "Sam sat on the box once but it survived." }
                }
            },
            "hotwheels.update": {
                "required": ["name", "detail"],
                "type": "object",
                "properties": {
                    "name": { "type": "string", "example": "Meow-stang GT500" },
                    "detail": { "type": "string", "example": "Updated after Silvia's quality inspection." }
                }
            },
            "ip.lookup": {
                "type": "object",
                "description": "Complete IP intelligence result. Sam sniffed it; Silvia documented it.",
                "properties": {
                    "ip": {
                        "type": "string",
                        "description": "The queried IP address",
                        "example": "118.25.6.39"
                    },
                    "location": {
                        "nullable": true,
                        "description": "Geolocation data from ip2location. Null if the IP is not in the database.",
                        "type": "object",
                        "properties": {
                            "country_code": { "type": "string", "example": "CN" },
                            "country_name": { "type": "string", "example": "China" },
                            "region_name": { "type": "string", "nullable": true, "example": "Guangdong" },
                            "city_name": { "type": "string", "nullable": true, "example": "Shenzhen" },
                            "latitude": { "type": "number", "format": "float", "nullable": true, "example": 22.5431 },
                            "longitude": { "type": "number", "format": "float", "nullable": true, "example": 114.0579 },
                            "zip_code": { "type": "string", "nullable": true, "example": "518000" },
                            "time_zone": { "type": "string", "nullable": true, "example": "+08:00" }
                        }
                    },
                    "country": {
                        "nullable": true,
                        "description": "Country reference data. Null if not in the reference table.",
                        "type": "object",
                        "properties": {
                            "alpha3_code": { "type": "string", "example": "CHN" },
                            "numeric_code": { "type": "string", "example": "156" },
                            "capital": { "type": "string", "nullable": true, "example": "Beijing" },
                            "currency_code": { "type": "string", "nullable": true, "example": "CNY" },
                            "currency_name": { "type": "string", "nullable": true, "example": "Yuan Renminbi" },
                            "currency_symbol": { "type": "string", "nullable": true, "example": "¥" },
                            "cctld": { "type": "string", "nullable": true, "example": ".cn" },
                            "idd_code": { "type": "string", "nullable": true, "example": "86" },
                            "population": { "type": "integer", "nullable": true, "example": 1411750000 },
                            "total_area": { "type": "integer", "nullable": true, "example": 9596960 }
                        }
                    },
                    "continent": {
                        "nullable": true,
                        "type": "object",
                        "properties": {
                            "code": { "type": "string", "example": "AS" },
                            "name": { "type": "string", "example": "Asia" }
                        }
                    },
                    "timezone": {
                        "nullable": true,
                        "type": "object",
                        "properties": {
                            "olson": { "type": "string", "example": "Asia/Shanghai" },
                            "abbreviation": { "type": "string", "nullable": true, "example": "CST" },
                            "dst_start": { "type": "string", "nullable": true, "example": null },
                            "dst_end": { "type": "string", "nullable": true, "example": null }
                        }
                    },
                    "metro": {
                        "nullable": true,
                        "description": "Metro area info (US only). Null outside the US — Sam is based in the Netherlands.",
                        "type": "object",
                        "properties": {
                            "code": { "type": "string", "example": "501" },
                            "name": { "type": "string", "example": "New York" }
                        }
                    },
                    "asn": {
                        "nullable": true,
                        "type": "object",
                        "properties": {
                            "asn": { "type": "string", "example": "AS45090" },
                            "organization": { "type": "string", "example": "Tencent Cloud Computing (Beijing) Co. Ltd" },
                            "network": { "type": "string", "example": "118.25.0.0/16" }
                        }
                    },
                    "threat": {
                        "type": "object",
                        "description": "Combined threat assessment from AbuseIPDB, ip2location proxy data, and custom score rules. Score ≥ 50 always sets `is_threat: true`. Silvia keeps score; Sam enforces it.",
                        "properties": {
                            "score": {
                                "type": "integer",
                                "description": "Threat score 0–100. Primary: AbuseIPDB `abuse_confidence_score` (per-IP, full weight). Secondary: ip2location `fraud_score` at 25% (block-level signal). Plus any custom country/rule modifiers. When AbuseIPDB data is unavailable, ip2location `fraud_score` is used as the sole base. Always clamped to 100.",
                                "example": 75
                            },
                            "is_proxy": { "type": "boolean", "description": "True if ip2location classifies this IP as a proxy or hosting range.", "example": true },
                            "is_vpn": { "type": "boolean", "description": "True if proxy type is VPN, TOR, or CPN.", "example": false },
                            "is_threat": { "type": "boolean", "description": "True when score ≥ 50 or ip2location reports an active threat category. Sam hisses at anything above 50.", "example": true },
                            "reasons": {
                                "type": "array",
                                "description": "Human-readable labels explaining the score. Includes proxy type, ip2location threat category, and any triggered score rules.",
                                "items": { "type": "string" },
                                "example": ["Hosting / data center IP", "Threat category: SPAM", "High-risk country: China"]
                            },
                            "total_reports": {
                                "type": "integer",
                                "nullable": true,
                                "description": "Total AbuseIPDB abuse reports filed against this IP in the last 90 days. Null if AbuseIPDB data is unavailable.",
                                "example": 42
                            },
                            "last_reported_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true,
                                "description": "ISO 8601 timestamp of the most recent AbuseIPDB report. Null if never reported or unavailable.",
                                "example": "2024-01-15T10:00:00+00:00"
                            },
                            "checked_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true,
                                "description": "When we last fetched AbuseIPDB data for this IP. Results are cached for 14 days — Silvia updates her records on schedule.",
                                "example": "2026-04-19T14:00:00+00:00"
                            },
                            "reports": {
                                "nullable": true,
                                "type": "array",
                                "description": "Up to 50 most recent AbuseIPDB reports for this IP. Null if AbuseIPDB data is unavailable. History is accumulated across checks — Silvia never forgets a grudge.",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "reported_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" },
                                        "categories": {
                                            "type": "array",
                                            "description": "AbuseIPDB category IDs (e.g. 18=Brute-Force, 22=SSH). Sam memorised them all.",
                                            "items": { "type": "integer" },
                                            "example": [18, 22]
                                        },
                                        "comment": { "type": "string", "nullable": true, "example": "Sam detected suspicious SSH traffic from this IP at 3 AM. He woke up the admin by sitting on the keyboard." },
                                        "reporter_country_code": { "type": "string", "nullable": true, "example": "NL" },
                                        "reporter_country_name": { "type": "string", "nullable": true, "example": "Netherlands" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "headers": {
            "X-RateLimit-Limit": {
                "description": "The maximum number of requests allowed in the current window. Silvia gets 1000 head-scritches per day — you get 1000 requests.",
                "schema": { "type": "integer", "example": 1000 }
            },
            "X-RateLimit-Remaining": {
                "description": "The number of requests remaining before the window resets. Sam is watching this number very carefully.",
                "schema": { "type": "integer", "example": 999 }
            },
            "X-RateLimit-Reset": {
                "description": "Unix timestamp (seconds) when the rate limit window resets. Silvia sets her nap timer to this.",
                "schema": { "type": "integer", "format": "int64", "example": 1745190000 }
            }
        },
        "securitySchemes": {
            "BearerToken": {
                "type": "http",
                "scheme": "bearer",
                "description": "A token obtained from `/auth/login`. Valid for 24 hours — about as long as Sam stays mad after you close the bathroom door. Place it in the `Authorization: Bearer <token>` header."
            }
        },
        "requestBodies": {
            "account.register": {
                "required": true,
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/account.register" }
                    }
                }
            },
            "account.verify": {
                "required": true,
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/account.verify" }
                    }
                }
            },
            "account.login": {
                "required": true,
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/account.login" }
                    }
                }
            },
            "product.store": {
                "required": true,
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/product.input" }
                    }
                }
            },
            "hotwheels.store": {
                "required": true,
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/hotwheels.input" }
                    }
                }
            },
            "hotwheels.update": {
                "required": true,
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/hotwheels.update" }
                    }
                }
            }
        },
        "responses": {
            "default401": {
                "description": "Unauthenticated — no valid Bearer token provided. Sam wants to see your credentials.",
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/response.error" },
                        "example": {
                            "success": false,
                            "code": 401,
                            "data": "",
                            "message": "Unauthenticated."
                        }
                    }
                }
            },
            "default404": {
                "description": "Not found — Sam looked everywhere, including under the sofa.",
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/response.error" },
                        "example": {
                            "success": false,
                            "code": 404,
                            "data": "",
                            "message": "Command not found with current user credentials"
                        }
                    }
                }
            },
            "default406": {
                "description": "Validation error — check the `data` object for field-level details. Silvia says fill in all the required fields.",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "success": { "type": "boolean", "example": false },
                                "code": { "type": "integer", "format": "int32", "example": 406 },
                                "message": { "type": "string", "example": "Validation Error." },
                                "data": {
                                    "type": "object",
                                    "example": {
                                        "name": ["The name field is required."],
                                        "email": ["The email field must be a valid email address."]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "default429": {
                "description": "Rate limit exceeded — even Silvia naps less than this. Check `Retry-After` and try again when the window resets.",
                "headers": {
                    "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
                    "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
                    "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" },
                    "Retry-After": {
                        "description": "Seconds until the rate limit window resets. Sam counted them himself.",
                        "schema": { "type": "integer", "example": 3600 }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/response.error" },
                        "example": {
                            "success": false,
                            "code": 429,
                            "message": "Too Many Requests — even Silvia naps less than this."
                        }
                    }
                }
            },
            "default505": {
                "description": "Request was not sent over HTTPS. Sam refuses to transmit plaintext — he has standards.",
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/response.error" },
                        "example": {
                            "success": false,
                            "code": 505,
                            "data": "",
                            "message": "Request was not send over HTTPS"
                        }
                    }
                }
            }
        }
    }
}