{
    "openapi": "3.0.0",
    "info": {
        "title": "CardBand API",
        "description": "REST API for the CardBand mobile and web apps (Phase 1).",
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "http://127.0.0.1:8000/",
            "description": "Current environment"
        }
    ],
    "paths": {
        "/api/v1/auth/register": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Create an account and email a 6-digit verification code",
                "operationId": "b9e746d77661fb8df55d0ac63e1ece77",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email",
                                    "password",
                                    "password_confirmation"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "example": "alex@example.com"
                                    },
                                    "password": {
                                        "type": "string",
                                        "example": "Passw0rdOK"
                                    },
                                    "password_confirmation": {
                                        "type": "string",
                                        "example": "Passw0rdOK"
                                    },
                                    "accepted_terms": {
                                        "type": "boolean",
                                        "example": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Account created, verification code sent"
                    },
                    "422": {
                        "description": "Validation failed"
                    }
                }
            }
        },
        "/api/v1/auth/verify-email": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Confirm the 6-digit email code. Returns an access token.",
                "operationId": "f408bbed20b1b46ac7cd6f3ea8972710",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email",
                                    "code"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "code": {
                                        "type": "string",
                                        "example": "482916"
                                    },
                                    "device_name": {
                                        "type": "string",
                                        "example": "iPhone 15"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Email verified; token returned"
                    },
                    "422": {
                        "description": "Invalid or expired code"
                    }
                }
            }
        },
        "/api/v1/auth/resend-verification": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Resend the verification code (once every 60 seconds)",
                "operationId": "ed6306c68c5f68375d96819d880893d5",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Code sent if the account needs it"
                    }
                }
            }
        },
        "/api/v1/auth/login": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Log in and receive a Bearer token",
                "operationId": "a7997e7c1e3bfed64d4e56de82415931",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email",
                                    "password"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "password": {
                                        "type": "string"
                                    },
                                    "device_name": {
                                        "type": "string",
                                        "example": "Pixel 8"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Logged in"
                    },
                    "403": {
                        "description": "Email not verified (code: email_not_verified)"
                    },
                    "422": {
                        "description": "Wrong credentials"
                    }
                }
            }
        },
        "/api/v1/auth/forgot-password": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Email a 6-digit password reset code",
                "operationId": "258f8322e6e587094f858db597dee996",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Always succeeds (no account enumeration)"
                    }
                }
            }
        },
        "/api/v1/auth/reset-password": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Set a new password using the emailed code",
                "operationId": "1032a68842312eda819d0b4888495d2b",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email",
                                    "code",
                                    "password",
                                    "password_confirmation"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "code": {
                                        "type": "string",
                                        "example": "482916"
                                    },
                                    "password": {
                                        "type": "string"
                                    },
                                    "password_confirmation": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Password changed; all sessions signed out"
                    },
                    "422": {
                        "description": "Invalid code or password"
                    }
                }
            }
        },
        "/api/v1/auth/logout": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Revoke the current token",
                "operationId": "f6b8957b4c0b25636613a9f0512a8ba9",
                "responses": {
                    "200": {
                        "description": "Logged out"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/auth/change-password": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Change password while signed in",
                "operationId": "f83da601e5c46325635cedf21eb6be3d",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "current_password",
                                    "password",
                                    "password_confirmation"
                                ],
                                "properties": {
                                    "current_password": {
                                        "type": "string"
                                    },
                                    "password": {
                                        "type": "string"
                                    },
                                    "password_confirmation": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Password changed; other devices signed out"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/auth/account": {
            "delete": {
                "tags": [
                    "Auth"
                ],
                "summary": "Delete the account (asks for the password)",
                "operationId": "667ec795ae736092cd302803313b5465",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "password"
                                ],
                                "properties": {
                                    "password": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Account deleted"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/binder": {
            "get": {
                "tags": [
                    "Trade Binder"
                ],
                "summary": "My Trade Binder (filters: status, source, offer_type, q; sort: newest|name|value)",
                "operationId": "605c6abc823b8ac778a79b869a767a0b",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "available",
                                "reserved",
                                "unavailable"
                            ]
                        }
                    },
                    {
                        "name": "source",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "web",
                                "mobile",
                                "scan"
                            ]
                        }
                    },
                    {
                        "name": "offer_type",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "trade",
                                "sale",
                                "sale_or_trade"
                            ]
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "newest",
                                "name",
                                "value"
                            ]
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated binder records"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Trade Binder"
                ],
                "summary": "Add a card to my binder (multipart when sending a photo). Graded: is_graded + grading_company + grade. Raw: condition.",
                "operationId": "c44d29d3b1c1bb183d63eb525b3b9cfb",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "card_id"
                                ],
                                "properties": {
                                    "card_id": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "quantity": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "is_graded": {
                                        "type": "boolean",
                                        "example": false
                                    },
                                    "condition": {
                                        "type": "string",
                                        "example": "near_mint",
                                        "enum": [
                                            "mint",
                                            "near_mint",
                                            "lightly_played",
                                            "moderately_played",
                                            "heavily_played",
                                            "damaged"
                                        ]
                                    },
                                    "grading_company": {
                                        "type": "string",
                                        "nullable": true,
                                        "enum": [
                                            "PSA",
                                            "BGS",
                                            "CGC",
                                            "SGC",
                                            "OTHER"
                                        ]
                                    },
                                    "grade": {
                                        "type": "number",
                                        "example": 8,
                                        "nullable": true
                                    },
                                    "cert_number": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "available",
                                            "reserved",
                                            "unavailable"
                                        ]
                                    },
                                    "offer_type": {
                                        "type": "string",
                                        "enum": [
                                            "trade",
                                            "sale",
                                            "sale_or_trade"
                                        ]
                                    },
                                    "asking_price": {
                                        "type": "number",
                                        "example": 185,
                                        "nullable": true
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Added"
                    },
                    "422": {
                        "description": "Validation failed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/binder/summary": {
            "get": {
                "tags": [
                    "Trade Binder"
                ],
                "summary": "Binder totals: records, available / reserved / unavailable, estimated value",
                "operationId": "779253179533709694a6971a4d08a0b8",
                "responses": {
                    "200": {
                        "description": "Summary"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/binder/value": {
            "get": {
                "tags": [
                    "Trade Binder"
                ],
                "summary": "Binder value with change since the last daily snapshot and 30-day history",
                "operationId": "76320f36895d8fc3911e69c78fba30a7",
                "responses": {
                    "200": {
                        "description": "Value report (estimates only)"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/binder/{id}": {
            "get": {
                "tags": [
                    "Trade Binder"
                ],
                "summary": "One binder record",
                "operationId": "f75c9970b1db6ba0e3b674f37a2f70ae",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The record"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Trade Binder"
                ],
                "summary": "Remove a card from my binder",
                "operationId": "302ef8bd73dd2399ac6b23ca3f0e79b6",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Removed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Trade Binder"
                ],
                "summary": "Edit a binder record (condition, grading, status, price, notes, photo)",
                "operationId": "30fa8cfd14f82471bf035794fb5237dd",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "available",
                                            "reserved",
                                            "unavailable"
                                        ]
                                    },
                                    "offer_type": {
                                        "type": "string",
                                        "enum": [
                                            "trade",
                                            "sale",
                                            "sale_or_trade"
                                        ]
                                    },
                                    "asking_price": {
                                        "type": "number",
                                        "nullable": true
                                    },
                                    "condition": {
                                        "type": "string"
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated record"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/binder/{id}/photo": {
            "delete": {
                "tags": [
                    "Trade Binder"
                ],
                "summary": "Remove my own photo from a binder record",
                "operationId": "0ed657804024764de5d65a81bf219fa7",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Updated record"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/cards": {
            "get": {
                "tags": [
                    "Cards"
                ],
                "summary": "Search the card catalogue (for Add card and \"Search & add a desired card\")",
                "operationId": "caaea73c66718ff13de334b48b79cd3f",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Name, set or number",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "collection_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated cards"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Cards"
                ],
                "summary": "Add a custom card when it is not in the catalogue (returns the existing card if it already exists)",
                "operationId": "76f926547a49ef5a68fef1b5ac0aac92",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "example": "Charizard"
                                    },
                                    "set_name": {
                                        "type": "string",
                                        "example": "Base Set",
                                        "nullable": true
                                    },
                                    "number": {
                                        "type": "string",
                                        "example": "4/102",
                                        "nullable": true
                                    },
                                    "year": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "rarity": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "language": {
                                        "type": "string",
                                        "example": "English",
                                        "nullable": true
                                    },
                                    "collection_id": {
                                        "type": "integer",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Card created"
                    },
                    "200": {
                        "description": "Already existed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/cards/{id}": {
            "get": {
                "tags": [
                    "Cards"
                ],
                "summary": "Card details",
                "operationId": "7b42cf72ae3be363d720b99c0949e6fa",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The card"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/catalog/collections": {
            "get": {
                "tags": [
                    "Catalog"
                ],
                "summary": "Collections to choose from during onboarding (Pokémon, Sports, ...)",
                "operationId": "33e6041c5aa64d47fcfa853da36d07aa",
                "responses": {
                    "200": {
                        "description": "List of collections"
                    }
                }
            }
        },
        "/api/v1/catalog/collect-types": {
            "get": {
                "tags": [
                    "Catalog"
                ],
                "summary": "What you collect: Vintage holos, Graded cards, Modern sets, Sealed",
                "operationId": "42886d99a6478f66d48f25307e0567d0",
                "responses": {
                    "200": {
                        "description": "List of collect types"
                    }
                }
            }
        },
        "/api/v1/collectors/{handle}": {
            "get": {
                "tags": [
                    "Collectors"
                ],
                "summary": "View another collector's public profile (with relationship and stats)",
                "operationId": "656f982a7bb7c95b2e41db224857da1a",
                "parameters": [
                    {
                        "name": "handle",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Public profile"
                    },
                    "404": {
                        "description": "Not found, private or blocked"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/collectors/{handle}/binder": {
            "get": {
                "tags": [
                    "Collectors"
                ],
                "summary": "A collector's Trade Binder (available and reserved cards) if they share it",
                "operationId": "d6e59ddb29d8092636683f92c6661eea",
                "parameters": [
                    {
                        "name": "handle",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated listings"
                    },
                    "403": {
                        "description": "Binder is private"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/collectors/{handle}/wish-list": {
            "get": {
                "tags": [
                    "Collectors"
                ],
                "summary": "A collector's wish list if they share it",
                "operationId": "57a1502796fdc325458c7db9ff77933e",
                "parameters": [
                    {
                        "name": "handle",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated wish-list entries"
                    },
                    "403": {
                        "description": "Wish list is private"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/collectors/{handle}/posts": {
            "get": {
                "tags": [
                    "Collectors"
                ],
                "summary": "Posts by a collector that I am allowed to see",
                "operationId": "614ff8a40ac748ea795a0fb628d467b3",
                "parameters": [
                    {
                        "name": "handle",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated posts"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/feed": {
            "get": {
                "tags": [
                    "Community"
                ],
                "summary": "Community feed. tab = for_you (ranked, default) | following | latest",
                "operationId": "e571cc871d180ca0f30953163caee63e",
                "parameters": [
                    {
                        "name": "tab",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "for_you",
                                "following",
                                "latest"
                            ]
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated posts"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me/posts": {
            "get": {
                "tags": [
                    "Community"
                ],
                "summary": "My posts. status = published (default) | draft (\"Draft Posts\")",
                "operationId": "2e8ee8cd52fa7577995cf25810290af3",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "published",
                                "draft"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated posts"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/posts": {
            "post": {
                "tags": [
                    "Community"
                ],
                "summary": "Create a post or save a draft (multipart). images[] + roles[] (front|back|extra) are parallel arrays.",
                "operationId": "c94133bdcb007cad08225345d4538cb1",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "properties": {
                                    "caption": {
                                        "type": "string"
                                    },
                                    "privacy": {
                                        "type": "string",
                                        "enum": [
                                            "public",
                                            "friends"
                                        ]
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "published",
                                            "draft"
                                        ]
                                    },
                                    "images[]": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary"
                                        }
                                    },
                                    "roles[]": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "front",
                                                "back",
                                                "extra"
                                            ]
                                        }
                                    },
                                    "tag_user_ids[]": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Post created"
                    },
                    "422": {
                        "description": "Validation failed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/posts/{id}": {
            "get": {
                "tags": [
                    "Community"
                ],
                "summary": "One post (my own drafts included)",
                "operationId": "b6b88999abbbfc5d5060140b6972366c",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The post"
                    },
                    "404": {
                        "description": "Not found or not visible"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Community"
                ],
                "summary": "Delete my post",
                "operationId": "5a8e7b7395a2e87ef6d2ce7b86e959fa",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Community"
                ],
                "summary": "Edit caption, privacy, tags or publish a draft (status = published)",
                "operationId": "8faced91fc72f2bb3ffb9f9bb0efb7db",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "caption": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "privacy": {
                                        "type": "string",
                                        "enum": [
                                            "public",
                                            "friends"
                                        ]
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "published"
                                        ]
                                    },
                                    "tag_user_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated post"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/posts/{id}/media": {
            "post": {
                "tags": [
                    "Community"
                ],
                "summary": "Add photos/videos to my post (multipart images[] + roles[])",
                "operationId": "f0d80b29d371d60b089d56410ff3c55e",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "properties": {
                                    "images[]": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary"
                                        }
                                    },
                                    "roles[]": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated post"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/posts/{id}/media/{mediaId}": {
            "delete": {
                "tags": [
                    "Community"
                ],
                "summary": "Remove one photo/video from my post",
                "operationId": "eb4eb884b0b1ec66b79c142fe718ffce",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "mediaId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Updated post"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/posts/{id}/like": {
            "post": {
                "tags": [
                    "Community"
                ],
                "summary": "Like a post (idempotent)",
                "operationId": "9bca09d56895bf31504167fbe7122119",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Updated counts"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Community"
                ],
                "summary": "Remove my like",
                "operationId": "66cafb7f8788ff5d486770c18edc8245",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Updated counts"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/posts/{id}/comments": {
            "get": {
                "tags": [
                    "Community"
                ],
                "summary": "Comments on a post, oldest first",
                "operationId": "12857cf0c6fb739bd8357464010143ce",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated comments"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Community"
                ],
                "summary": "Add a comment",
                "operationId": "460368dc7f80b4611f0fe97c8b0c1a86",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "body"
                                ],
                                "properties": {
                                    "body": {
                                        "type": "string",
                                        "example": "Great pull!"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Comment created"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/comments/{id}": {
            "delete": {
                "tags": [
                    "Community"
                ],
                "summary": "Delete a comment (its author or the post owner)",
                "operationId": "6e4b6cb50847a6696bc8aed481bdeca5",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted"
                    },
                    "403": {
                        "description": "Not allowed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/connections/summary": {
            "get": {
                "tags": [
                    "Connections"
                ],
                "summary": "Counts for the Connections tabs: friends, followers, following, pending requests",
                "operationId": "9a8feb63d04294c41cbd7760614b2cba",
                "responses": {
                    "200": {
                        "description": "Counts"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/friends": {
            "get": {
                "tags": [
                    "Connections"
                ],
                "summary": "My friends (\"Connected\"). Optional search by name or handle.",
                "operationId": "d84486a59e2e3c7f577038b4d079977b",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated friends"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/friends/requests": {
            "get": {
                "tags": [
                    "Connections"
                ],
                "summary": "Friend requests. direction=received (default, \"Pending\") or sent",
                "operationId": "b62c77ba7721bcfb6dd0d423af4dd07f",
                "parameters": [
                    {
                        "name": "direction",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "received",
                                "sent"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Pending requests"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Connections"
                ],
                "summary": "Send a friend request (if they already asked you, it is accepted)",
                "operationId": "6a1d347224da174d79944ffe053bffb8",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "handle"
                                ],
                                "properties": {
                                    "handle": {
                                        "type": "string",
                                        "example": "maya_chen22"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Request sent"
                    },
                    "422": {
                        "description": "Not allowed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/friends/requests/{id}/accept": {
            "post": {
                "tags": [
                    "Connections"
                ],
                "summary": "Accept a request you received",
                "operationId": "c635e1f490c0d5ab6c511fb6ef387869",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Accepted"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/friends/requests/{id}": {
            "delete": {
                "tags": [
                    "Connections"
                ],
                "summary": "Decline (\"Ignore\") a received request or cancel one you sent",
                "operationId": "3880567b3f36917a5d491cac53f4636c",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Removed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/friends/{handle}": {
            "delete": {
                "tags": [
                    "Connections"
                ],
                "summary": "Unfriend",
                "operationId": "3f8bf4221d287942d667ffe9c7f8386b",
                "parameters": [
                    {
                        "name": "handle",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Unfriended"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/following": {
            "get": {
                "tags": [
                    "Connections"
                ],
                "summary": "Collectors I follow",
                "operationId": "f5a261c30fd56edc1d0698b67f63f4ac",
                "responses": {
                    "200": {
                        "description": "Paginated"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/followers": {
            "get": {
                "tags": [
                    "Connections"
                ],
                "summary": "Collectors who follow me",
                "operationId": "afd6919b061c0fef6b0b0dc21d15151a",
                "responses": {
                    "200": {
                        "description": "Paginated"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/follows": {
            "post": {
                "tags": [
                    "Connections"
                ],
                "summary": "Follow a collector",
                "operationId": "9610b5ccb2ff539c8b14998734b7a76d",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "handle"
                                ],
                                "properties": {
                                    "handle": {
                                        "type": "string",
                                        "example": "j_lee88"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Now following"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/follows/{handle}": {
            "delete": {
                "tags": [
                    "Connections"
                ],
                "summary": "Unfollow a collector",
                "operationId": "09a2e83ae47fc2fb0deb524eac1b4640",
                "parameters": [
                    {
                        "name": "handle",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Unfollowed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/blocks": {
            "get": {
                "tags": [
                    "Connections"
                ],
                "summary": "Collectors I blocked (Settings → Blocked accounts)",
                "operationId": "c0f3c9f36cd2c7f978683ba8f9d04f46",
                "responses": {
                    "200": {
                        "description": "Blocked collectors with the block date"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Connections"
                ],
                "summary": "Block a collector (removes friendship and follows both ways)",
                "operationId": "451ed7b0e8b2c749aac0863bfd9bc14e",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "handle"
                                ],
                                "properties": {
                                    "handle": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Blocked"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/blocks/{handle}": {
            "delete": {
                "tags": [
                    "Connections"
                ],
                "summary": "Unblock a collector",
                "operationId": "c6bc524cd400add447e5ceb8f546f0d4",
                "parameters": [
                    {
                        "name": "handle",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Unblocked"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/discover/collectors": {
            "get": {
                "tags": [
                    "Discovery"
                ],
                "summary": "Find collectors (\"Refine discovery\"): search + filters, ranked by what you have in common",
                "operationId": "f13df23808834b631f5baf34e6c06f24",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Name or handle",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "intent",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "buying",
                                "selling",
                                "trading"
                            ]
                        }
                    },
                    {
                        "name": "collection_ids[]",
                        "in": "query",
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "integer"
                            }
                        }
                    },
                    {
                        "name": "city",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "2-letter code",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated collectors with relationship and match_reasons"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/discover/recommended": {
            "get": {
                "tags": [
                    "Discovery"
                ],
                "summary": "\"Recommended for you\": best matches not yet connected (default 5, max 20)",
                "operationId": "f2b50c9aedbc8194381f34b0a72f7314",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recommended collectors"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/events": {
            "get": {
                "tags": [
                    "Events"
                ],
                "summary": "Events. tab = discover (default) | attending | saved | past. Filters: q, city, country, from/to (dates), lat+lng+radius_miles.",
                "operationId": "1845dc9126717378ecce57f9863a2775",
                "parameters": [
                    {
                        "name": "tab",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "discover",
                                "attending",
                                "saved",
                                "past"
                            ]
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "city",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "description": "YYYY-MM-DD",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "description": "YYYY-MM-DD",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "lat",
                        "in": "query",
                        "schema": {
                            "type": "number"
                        }
                    },
                    {
                        "name": "lng",
                        "in": "query",
                        "schema": {
                            "type": "number"
                        }
                    },
                    {
                        "name": "radius_miles",
                        "in": "query",
                        "schema": {
                            "type": "number"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated events with my attendance state"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/events/{id}": {
            "get": {
                "tags": [
                    "Events"
                ],
                "summary": "Event details with my status, attending count and friends going",
                "operationId": "954b2484f2b7374943e532424808976b",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The event"
                    },
                    "404": {
                        "description": "Not found / not published"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/events/{id}/attend": {
            "post": {
                "tags": [
                    "Events"
                ],
                "summary": "Register to attend (\"Attend\")",
                "operationId": "bf8cfdb8baa2fdee34f24fa5adc4c518",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Updated event"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Events"
                ],
                "summary": "Cancel my attendance",
                "operationId": "af83b94fcc86b1271e4cbb52a6b4cc5a",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Updated event"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/events/{id}/save": {
            "post": {
                "tags": [
                    "Events"
                ],
                "summary": "Save an event (bookmark)",
                "operationId": "f706f658056e1626442cb5d409ccc54c",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Updated event"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Events"
                ],
                "summary": "Remove from saved",
                "operationId": "332d7b47213f3ab335a0117f834526a1",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Updated event"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/events/{id}/check-in": {
            "post": {
                "tags": [
                    "Events"
                ],
                "summary": "Mobile: check in with your location (within the event radius) or the code shown at the venue. Opens 2 h before the start, closes 2 h after the end.",
                "operationId": "608823b32313fe13690db58a672008d6",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "latitude": {
                                        "type": "number",
                                        "example": 47.6062
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "example": -122.3321
                                    },
                                    "code": {
                                        "type": "string",
                                        "example": "SEA2026",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Checked in"
                    },
                    "422": {
                        "description": "Too far, closed, or wrong code"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/events/{id}/event-mode": {
            "post": {
                "tags": [
                    "Events"
                ],
                "summary": "Turn on Event Mode (Premium; needs check-in): matches your wish list with other checked-in collectors",
                "operationId": "f89cc53da9504a45f7b6424c16fb3cd1",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Event Mode on"
                    },
                    "403": {
                        "description": "Premium required (errors.code = upgrade_required)"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Events"
                ],
                "summary": "Turn Event Mode off (also stops sharing your approximate location)",
                "operationId": "bf9c7d7c17d859c6b4ef144b5ffd85a0",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Event Mode off"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/events/{id}/location": {
            "post": {
                "tags": [
                    "Events"
                ],
                "summary": "Mobile: share my approximate position while Event Mode is on (send every ~1-2 min). Used for rough \"how far\" hints only.",
                "operationId": "ef19ba4f3f316ac39590b24c1d59e780",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "latitude",
                                    "longitude"
                                ],
                                "properties": {
                                    "latitude": {
                                        "type": "number"
                                    },
                                    "longitude": {
                                        "type": "number"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Saved"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/events/{id}/matches": {
            "get": {
                "tags": [
                    "Events"
                ],
                "summary": "Event matches: cards from other checked-in collectors that satisfy my wish list, nearest first (web: view only)",
                "operationId": "ad9f45236569c9565dccd78d460a8763",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Matches"
                    },
                    "422": {
                        "description": "Not checked in / Event Mode off"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/health": {
            "get": {
                "tags": [
                    "System"
                ],
                "summary": "API health check",
                "operationId": "08446b2131153d4d904a591df15d8495",
                "responses": {
                    "200": {
                        "description": "API is up"
                    }
                }
            }
        },
        "/api/v1/marketplace": {
            "get": {
                "tags": [
                    "Marketplace"
                ],
                "summary": "Browse cards other collectors have available. type = all | for_sale | for_trade. No checkout in Phase 1.",
                "operationId": "4bdad7b5e93496821a688968cf367b0f",
                "parameters": [
                    {
                        "name": "type",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "all",
                                "for_sale",
                                "for_trade"
                            ]
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Card name, set or number",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "collection_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "newest",
                                "price_asc",
                                "price_desc"
                            ]
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated listings"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/marketplace/{id}": {
            "get": {
                "tags": [
                    "Marketplace"
                ],
                "summary": "Card detail: price, estimated market value, grade/condition and the owner (message them to talk)",
                "operationId": "9fa25c0bdf488c674ae798e87fd026bf",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Listing"
                    },
                    "404": {
                        "description": "Not available"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/membership/plans": {
            "get": {
                "tags": [
                    "Membership"
                ],
                "summary": "Available membership plans (price, interval and features are admin-managed)",
                "operationId": "bfaa0a95d473840d638835a33ff66097",
                "responses": {
                    "200": {
                        "description": "Plans"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/membership": {
            "get": {
                "tags": [
                    "Membership"
                ],
                "summary": "My membership: plan, status, renewal date, entitlements and usage (scans / binder / wish list vs limits)",
                "operationId": "15e50a9913fac160939b1d50c61dbd58",
                "responses": {
                    "200": {
                        "description": "Membership status"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/membership/refresh": {
            "post": {
                "tags": [
                    "Membership"
                ],
                "summary": "\"Refresh status\": re-read my subscription from the payment provider",
                "operationId": "a62a84b14e269c8ccd53ad1c60665857",
                "responses": {
                    "200": {
                        "description": "Updated membership status"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/membership/redeem": {
            "post": {
                "tags": [
                    "Membership"
                ],
                "summary": "Redeem a promotional code for Premium access",
                "operationId": "132b4200b1904a42a3724144c4571b99",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "code"
                                ],
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "example": "WELCOME30"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Code redeemed"
                    },
                    "422": {
                        "description": "Invalid, expired or already used"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/membership/checkout": {
            "post": {
                "tags": [
                    "Membership"
                ],
                "summary": "Web: start a Stripe Checkout for a plan. Returns the URL to redirect to.",
                "operationId": "32b5ee17bf9349f0dd7fc9cb5807f1ce",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "plan_key"
                                ],
                                "properties": {
                                    "plan_key": {
                                        "type": "string",
                                        "example": "premium"
                                    },
                                    "success_url": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "cancel_url": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "{ checkout_url }"
                    },
                    "422": {
                        "description": "Plan not purchasable on web / already subscribed"
                    },
                    "503": {
                        "description": "Payments not configured yet"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/membership/portal": {
            "post": {
                "tags": [
                    "Membership"
                ],
                "summary": "Web: \"Manage via provider\" – opens the Stripe billing portal (change card, cancel). Returns the URL.",
                "operationId": "7ea80f4d6087d67ff2e7ab51a89ac672",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "return_url": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "{ portal_url }"
                    },
                    "503": {
                        "description": "Payments not configured yet"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/conversations": {
            "get": {
                "tags": [
                    "Messages"
                ],
                "summary": "My conversations, newest first, with unread counts (poll every ~15-30 s). q searches the other collector.",
                "operationId": "78a70fe3dde67daccc548e3f4ae130eb",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated conversations"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Messages"
                ],
                "summary": "Start (or continue) a conversation with a collector and send the first message. Optional binder_item_id = \"about this card\" (Message collector).",
                "operationId": "b52a26ce36998f6fc1db8de618239175",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "handle",
                                    "body"
                                ],
                                "properties": {
                                    "handle": {
                                        "type": "string",
                                        "example": "maya_chen22"
                                    },
                                    "body": {
                                        "type": "string",
                                        "example": "Hi Maya, is your Mewtwo still available?"
                                    },
                                    "binder_item_id": {
                                        "type": "integer",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Conversation + first message"
                    },
                    "403": {
                        "description": "Collector is not accepting private messages"
                    },
                    "404": {
                        "description": "Collector not found or blocked"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/conversations/unread": {
            "get": {
                "tags": [
                    "Messages"
                ],
                "summary": "Unread totals for the Messages badge",
                "operationId": "b0cd620f288974cf9874ae00b83beaeb",
                "responses": {
                    "200": {
                        "description": "{ unread_messages, unread_conversations }"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/conversations/{id}": {
            "get": {
                "tags": [
                    "Messages"
                ],
                "summary": "Conversation header (the other collector, \"Connected\" badge via relationship, unread count)",
                "operationId": "0f352e964d71e637f0d25ad0670ccfd0",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Conversation"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Messages"
                ],
                "summary": "Delete the conversation for me only (it comes back if they write again)",
                "operationId": "32864aa60a2f82c14f99d204ce1cdcc9",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted for me"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/conversations/{id}/messages": {
            "get": {
                "tags": [
                    "Messages"
                ],
                "summary": "Messages oldest → newest. Poll with after_id (last message id you have) every ~3-5 s while the chat is open; page back with before_id.",
                "operationId": "f7946ae7dd5cc2783c95ba31adb140db",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "after_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "before_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Messages; meta.has_more tells whether older ones exist"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Messages"
                ],
                "summary": "Send a message",
                "operationId": "52b43c6b5d8fe4a8324a5a24012f401a",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "body"
                                ],
                                "properties": {
                                    "body": {
                                        "type": "string"
                                    },
                                    "binder_item_id": {
                                        "type": "integer",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Message sent"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/conversations/{id}/read": {
            "post": {
                "tags": [
                    "Messages"
                ],
                "summary": "Mark the conversation as read (call when the chat is opened / new messages are shown)",
                "operationId": "947f9c906623c4c78ec42cf073b0eca0",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Marked as read"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/notifications": {
            "get": {
                "tags": [
                    "Notifications"
                ],
                "summary": "In-app notifications, newest first (unread_only=1 for unread only)",
                "operationId": "cac3bdde44f0be0512f7d05c0a6064e4",
                "parameters": [
                    {
                        "name": "unread_only",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated notifications"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/notifications/unread-count": {
            "get": {
                "tags": [
                    "Notifications"
                ],
                "summary": "Unread notification count (bell badge)",
                "operationId": "9fd717daa9c0cfd209252ee25d0715ea",
                "responses": {
                    "200": {
                        "description": "{ unread }"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/notifications/{id}/read": {
            "post": {
                "tags": [
                    "Notifications"
                ],
                "summary": "Mark one notification as read",
                "operationId": "3b045f1ec2d4d8d5a947b5860de67667",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Marked as read"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/notifications/read-all": {
            "post": {
                "tags": [
                    "Notifications"
                ],
                "summary": "Mark every notification as read",
                "operationId": "82b1f86a42d93de117630c0434de1645",
                "responses": {
                    "200": {
                        "description": "All read"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me/counters": {
            "get": {
                "tags": [
                    "Notifications"
                ],
                "summary": "One call for every badge: unread messages / notifications, pending friend requests, ratings waiting to be given. Poll every ~30 s.",
                "operationId": "f70da949fad30d2d1c9c80077e55cd14",
                "responses": {
                    "200": {
                        "description": "Counters"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me/notification-settings": {
            "get": {
                "tags": [
                    "Notifications"
                ],
                "summary": "Notification switches (Settings → Notifications)",
                "operationId": "754214d88c014a25fb069b058c6b5440",
                "responses": {
                    "200": {
                        "description": "Settings"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Notifications"
                ],
                "summary": "Update notification switches (send only the ones that change)",
                "operationId": "d69088b4a86482d83b15e37f1f04e52e",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "direct_messages": {
                                        "type": "boolean"
                                    },
                                    "connections": {
                                        "type": "boolean"
                                    },
                                    "comments_ratings": {
                                        "type": "boolean"
                                    },
                                    "wishlist_matches": {
                                        "type": "boolean"
                                    },
                                    "followed_activity": {
                                        "type": "boolean"
                                    },
                                    "event_reminders": {
                                        "type": "boolean"
                                    },
                                    "advanced_event_matches": {
                                        "description": "Premium feature",
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated settings"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/devices": {
            "post": {
                "tags": [
                    "Notifications"
                ],
                "summary": "Register this device for push notifications (FCM token). Safe to call on every app start.",
                "operationId": "bef4a019ca413328fad6b67209a02f4a",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "token",
                                    "platform"
                                ],
                                "properties": {
                                    "token": {
                                        "type": "string"
                                    },
                                    "platform": {
                                        "type": "string",
                                        "enum": [
                                            "ios",
                                            "android",
                                            "web"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Registered"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Notifications"
                ],
                "summary": "Unregister this device (call on logout)",
                "operationId": "2ea492a11a2e274fe404dbb747fbfc2c",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "token"
                                ],
                                "properties": {
                                    "token": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Unregistered"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me": {
            "get": {
                "tags": [
                    "Profile"
                ],
                "summary": "Current collector profile, preferences, privacy and onboarding progress",
                "operationId": "df361bae9ea631d3912cb371ff33ecb3",
                "responses": {
                    "200": {
                        "description": "The signed-in collector"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Profile"
                ],
                "summary": "Update display name, handle, bio and city",
                "operationId": "e4650f49869ff84cd1e70055573fd8a9",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "display_name": {
                                        "type": "string",
                                        "example": "Alex Rivera"
                                    },
                                    "handle": {
                                        "description": "3-30 chars: a-z, 0-9, underscore. Stored without @.",
                                        "type": "string",
                                        "example": "alexcollects"
                                    },
                                    "bio": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "city": {
                                        "type": "string",
                                        "example": "Seattle, WA",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated profile"
                    },
                    "422": {
                        "description": "Validation failed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/handles/check": {
            "get": {
                "tags": [
                    "Profile"
                ],
                "summary": "Is this handle free?",
                "operationId": "cf1583d1d83745ae4a4375e0ca26cda3",
                "parameters": [
                    {
                        "name": "handle",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "{ available: bool }"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me/avatar": {
            "post": {
                "tags": [
                    "Profile"
                ],
                "summary": "Upload profile photo (multipart, field: image)",
                "operationId": "9901f9310c39fb2a95031dcf40c546b3",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "properties": {
                                    "image": {
                                        "type": "string",
                                        "format": "binary"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated profile"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Profile"
                ],
                "summary": "Remove profile photo",
                "operationId": "7a19cf432a82f6ce80f08bb7cf445850",
                "responses": {
                    "200": {
                        "description": "Updated profile"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me/cover": {
            "post": {
                "tags": [
                    "Profile"
                ],
                "summary": "Upload cover photo (multipart, field: image)",
                "operationId": "65a1aa6b7b8ca6fe007fee38723c3fdb",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "properties": {
                                    "image": {
                                        "type": "string",
                                        "format": "binary"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated profile"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Profile"
                ],
                "summary": "Remove cover photo",
                "operationId": "1d2c6c98ac80dbaad209ff0268c48211",
                "responses": {
                    "200": {
                        "description": "Updated profile"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me/intents": {
            "put": {
                "tags": [
                    "Profile"
                ],
                "summary": "Set primary intent (multi-select): buying, selling, trading",
                "operationId": "9bff19fc80fbf4da93840c8422993efa",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "intents"
                                ],
                                "properties": {
                                    "intents": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "buying",
                                                "selling",
                                                "trading"
                                            ]
                                        },
                                        "example": [
                                            "trading",
                                            "buying"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated profile"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me/preferences": {
            "put": {
                "tags": [
                    "Profile"
                ],
                "summary": "Collecting preferences: collections, what you collect, shipping radius",
                "operationId": "11bcb3ea2928de75f6bff97c6a47a3c2",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "collection_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        },
                                        "example": [
                                            1,
                                            3
                                        ]
                                    },
                                    "collect_type_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        },
                                        "example": [
                                            1
                                        ]
                                    },
                                    "radius_miles": {
                                        "type": "integer",
                                        "example": 25,
                                        "nullable": true
                                    },
                                    "shipping_country": {
                                        "type": "string",
                                        "example": "US",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated profile; onboarding completes when profile, intent and collections exist"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me/privacy": {
            "put": {
                "tags": [
                    "Profile"
                ],
                "summary": "Privacy and recommendation switches (Settings)",
                "operationId": "93741a5bb1d90a32e09c8a231d8b4435",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "is_profile_public": {
                                        "type": "boolean"
                                    },
                                    "show_trade_binder": {
                                        "type": "boolean"
                                    },
                                    "show_wish_list": {
                                        "type": "boolean"
                                    },
                                    "allow_private_messages": {
                                        "type": "boolean"
                                    },
                                    "personalized_recommendations": {
                                        "type": "boolean"
                                    },
                                    "share_event_location": {
                                        "description": "Share an approximate position with other checked-in collectors while Event Mode is on",
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated profile"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/reports": {
            "post": {
                "tags": [
                    "Reports"
                ],
                "summary": "Report a collector, post or comment to the moderators",
                "operationId": "fd7e22f67dcae4d1e2b5422f105b41e2",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "type",
                                    "id",
                                    "reason"
                                ],
                                "properties": {
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "user",
                                            "post",
                                            "comment",
                                            "message",
                                            "rating"
                                        ]
                                    },
                                    "id": {
                                        "type": "integer",
                                        "example": 12
                                    },
                                    "reason": {
                                        "type": "string",
                                        "enum": [
                                            "suspicious_account",
                                            "inappropriate_content",
                                            "fraud",
                                            "harassment",
                                            "negative_experience",
                                            "other"
                                        ]
                                    },
                                    "details": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Report received"
                    },
                    "422": {
                        "description": "Validation failed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/reputation": {
            "get": {
                "tags": [
                    "Reputation"
                ],
                "summary": "My reputation: average, ratings received, % Trusted, ratings given and waiting to be given",
                "operationId": "fbbfca21ba0a80ff8f179ae3817e2d93",
                "responses": {
                    "200": {
                        "description": "Summary"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/reputation/received": {
            "get": {
                "tags": [
                    "Reputation"
                ],
                "summary": "Ratings I received (\"Ratings history\")",
                "operationId": "317fc37a3e0ff232ff787be25b4a3bef",
                "responses": {
                    "200": {
                        "description": "Paginated ratings"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/reputation/given": {
            "get": {
                "tags": [
                    "Reputation"
                ],
                "summary": "Ratings I gave",
                "operationId": "fc34ae34a0421e7f7a2c14fa22eb4627",
                "responses": {
                    "200": {
                        "description": "Paginated ratings"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/reputation/eligible": {
            "get": {
                "tags": [
                    "Reputation"
                ],
                "summary": "\"Eligible to rate\": collectors I can rate now, with the confirmed interaction",
                "operationId": "c51a71bb56d6549a7e27c69f804f40a0",
                "responses": {
                    "200": {
                        "description": "Paginated eligibilities"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/ratings": {
            "post": {
                "tags": [
                    "Reputation"
                ],
                "summary": "Rate a collector for an eligible interaction (1-5 stars; 1-2 stars need a comment of 10+ characters)",
                "operationId": "ddaaf000dbd839babb0cb05038caa1c3",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "eligibility_id",
                                    "stars"
                                ],
                                "properties": {
                                    "eligibility_id": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "stars": {
                                        "type": "integer",
                                        "example": 5,
                                        "maximum": 5,
                                        "minimum": 1
                                    },
                                    "comment": {
                                        "type": "string",
                                        "example": "Friendly and helpful about card condition.",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Rating submitted"
                    },
                    "422": {
                        "description": "Already rated, expired, or low rating without a comment"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/collectors/{handle}/reputation": {
            "get": {
                "tags": [
                    "Reputation"
                ],
                "summary": "Another collector's reputation and recent ratings",
                "operationId": "c16080f28cc640896a605766024128dc",
                "parameters": [
                    {
                        "name": "handle",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Summary + paginated ratings"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/scans": {
            "get": {
                "tags": [
                    "Scans"
                ],
                "summary": "Previously scanned cards (filter: all | in_binder | unlinked, q)",
                "operationId": "cb2731fd2d2085997ae349b7097c774d",
                "parameters": [
                    {
                        "name": "filter",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "all",
                                "in_binder",
                                "unlinked"
                            ]
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated scans"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Scans"
                ],
                "summary": "Mobile: scan a card (multipart: front required, back optional). Returns the identification for review.",
                "operationId": "78bf8a8bc3cc14d630a235772e118eff",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "required": [
                                    "front"
                                ],
                                "properties": {
                                    "front": {
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "back": {
                                        "type": "string",
                                        "format": "binary"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Scan stored: identified | unmatched | failed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/scans/summary": {
            "get": {
                "tags": [
                    "Scans"
                ],
                "summary": "Tab counts: all / in binder / unlinked",
                "operationId": "a6644a2f921ee369bbeace3948506831",
                "responses": {
                    "200": {
                        "description": "Counts"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/scans/{id}": {
            "get": {
                "tags": [
                    "Scans"
                ],
                "summary": "One scan",
                "operationId": "cfa91e0805b8181ca91bbc766535f42c",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The scan"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Scans"
                ],
                "summary": "Remove a scan record (the binder record, if any, stays)",
                "operationId": "d415595de7afebee15a3d3a2cae4e7bb",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Removed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Scans"
                ],
                "summary": "Correct the identified card (card_id) or link / unlink a binder record (binder_item_id, null to unlink)",
                "operationId": "4198e570fba7656b36308c81e9f7fe9c",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "card_id": {
                                        "type": "integer"
                                    },
                                    "binder_item_id": {
                                        "type": "integer",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated scan"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/scans/{id}/add-to-binder": {
            "post": {
                "tags": [
                    "Scans"
                ],
                "summary": "Add the scanned card to my binder (graded details pre-filled when detected)",
                "operationId": "fc9e4fc159e67719854d36397c50d5bd",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "condition": {
                                        "type": "string",
                                        "example": "near_mint"
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "available",
                                            "reserved",
                                            "unavailable"
                                        ]
                                    },
                                    "offer_type": {
                                        "type": "string",
                                        "enum": [
                                            "trade",
                                            "sale",
                                            "sale_or_trade"
                                        ]
                                    },
                                    "asking_price": {
                                        "type": "number",
                                        "nullable": true
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Scan now linked to the new binder record"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me/settings": {
            "get": {
                "tags": [
                    "Settings"
                ],
                "summary": "Everything the Settings page needs in one call: privacy, preferences, notifications, membership summary",
                "operationId": "18daf60844f9b63e9608e7702e4dce90",
                "responses": {
                    "200": {
                        "description": "Settings overview"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me/sessions": {
            "get": {
                "tags": [
                    "Settings"
                ],
                "summary": "Devices / sessions signed in to my account (Security)",
                "operationId": "22d1d86205ca886c3ca55409bc8a9605",
                "responses": {
                    "200": {
                        "description": "Sessions"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Settings"
                ],
                "summary": "Sign out every other device (keeps this one)",
                "operationId": "e223ef97ceb2c923578411e7ab3e994b",
                "responses": {
                    "200": {
                        "description": "Other devices signed out"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/me/sessions/{id}": {
            "delete": {
                "tags": [
                    "Settings"
                ],
                "summary": "Sign out one device",
                "operationId": "6654165c7cad200228583ddc0d1e34c6",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Signed out"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/webhooks/stripe": {
            "post": {
                "tags": [
                    "Webhooks"
                ],
                "summary": "Stripe webhook (signature verified with STRIPE_WEBHOOK_SECRET). Not for apps.",
                "operationId": "27314572850088c2f3256c2afef81e7e",
                "responses": {
                    "200": {
                        "description": "Received"
                    },
                    "400": {
                        "description": "Bad signature"
                    }
                }
            }
        },
        "/api/v1/webhooks/revenuecat": {
            "post": {
                "tags": [
                    "Webhooks"
                ],
                "summary": "RevenueCat webhook for Apple / Google subscriptions (Authorization header = REVENUECAT_WEBHOOK_AUTH). Not for apps.",
                "operationId": "ecdcbdaeeb8973853ea33f2941df3891",
                "responses": {
                    "200": {
                        "description": "Received"
                    },
                    "401": {
                        "description": "Bad authorization"
                    }
                }
            }
        },
        "/api/v1/wish-list": {
            "get": {
                "tags": [
                    "Wish List"
                ],
                "summary": "My wish list with match counts (filters: priority, matched=1, q)",
                "operationId": "5017459ca50cb89519f1f60071be5d90",
                "parameters": [
                    {
                        "name": "priority",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "high",
                                "medium",
                                "low"
                            ]
                        }
                    },
                    {
                        "name": "matched",
                        "in": "query",
                        "description": "1 = only entries that have a match",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated wish-list entries"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Wish List"
                ],
                "summary": "Add a desired card",
                "operationId": "7d64b0eebe52a1de0cb948ce99d3c702",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "card_id"
                                ],
                                "properties": {
                                    "card_id": {
                                        "type": "integer",
                                        "example": 2
                                    },
                                    "priority": {
                                        "type": "string",
                                        "enum": [
                                            "high",
                                            "medium",
                                            "low"
                                        ]
                                    },
                                    "min_condition": {
                                        "type": "string",
                                        "example": "near_mint",
                                        "nullable": true
                                    },
                                    "grading_pref": {
                                        "type": "string",
                                        "enum": [
                                            "any",
                                            "ungraded",
                                            "graded"
                                        ]
                                    },
                                    "grading_company": {
                                        "type": "string",
                                        "example": "PSA",
                                        "nullable": true
                                    },
                                    "min_grade": {
                                        "type": "number",
                                        "example": 7,
                                        "nullable": true
                                    },
                                    "max_price": {
                                        "type": "number",
                                        "nullable": true
                                    },
                                    "quantity": {
                                        "type": "integer"
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Added"
                    },
                    "422": {
                        "description": "Already on your wish list / invalid"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/wish-list/summary": {
            "get": {
                "tags": [
                    "Wish List"
                ],
                "summary": "Counts for the tabs (All / High priority / Matched) and \"N collectors match your wish list\"",
                "operationId": "cef5c7981a720a71b50ac556690528ae",
                "responses": {
                    "200": {
                        "description": "Summary"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/wish-list/{id}": {
            "get": {
                "tags": [
                    "Wish List"
                ],
                "summary": "One wish-list entry",
                "operationId": "f9e9790931256f68963c2063d5234269",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The entry"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Wish List"
                ],
                "summary": "Remove from my wish list",
                "operationId": "f23b364dcfe7580dc5eeb6e9a283eeab",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Removed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Wish List"
                ],
                "summary": "Edit a wish-list entry",
                "operationId": "65b747a72d7212d23f8be2a133b4efe7",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "priority": {
                                        "type": "string",
                                        "enum": [
                                            "high",
                                            "medium",
                                            "low"
                                        ]
                                    },
                                    "min_condition": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "grading_pref": {
                                        "type": "string",
                                        "enum": [
                                            "any",
                                            "ungraded",
                                            "graded"
                                        ]
                                    },
                                    "max_price": {
                                        "type": "number",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/wish-list/{id}/matches": {
            "get": {
                "tags": [
                    "Wish List"
                ],
                "summary": "Collectors' binder cards that match this wish-list entry (\"View match\")",
                "operationId": "db3093b8a293a9531386b646667f1ac1",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated matching listings"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "bearerFormat": "Sanctum token",
                "scheme": "bearer"
            }
        }
    },
    "tags": [
        {
            "name": "Auth",
            "description": "Auth"
        },
        {
            "name": "Trade Binder",
            "description": "Trade Binder"
        },
        {
            "name": "Cards",
            "description": "Cards"
        },
        {
            "name": "Catalog",
            "description": "Catalog"
        },
        {
            "name": "Collectors",
            "description": "Collectors"
        },
        {
            "name": "Community",
            "description": "Community"
        },
        {
            "name": "Connections",
            "description": "Connections"
        },
        {
            "name": "Discovery",
            "description": "Discovery"
        },
        {
            "name": "Events",
            "description": "Events"
        },
        {
            "name": "System",
            "description": "System"
        },
        {
            "name": "Marketplace",
            "description": "Marketplace"
        },
        {
            "name": "Membership",
            "description": "Membership"
        },
        {
            "name": "Messages",
            "description": "Messages"
        },
        {
            "name": "Notifications",
            "description": "Notifications"
        },
        {
            "name": "Profile",
            "description": "Profile"
        },
        {
            "name": "Reports",
            "description": "Reports"
        },
        {
            "name": "Reputation",
            "description": "Reputation"
        },
        {
            "name": "Scans",
            "description": "Scans"
        },
        {
            "name": "Settings",
            "description": "Settings"
        },
        {
            "name": "Webhooks",
            "description": "Webhooks"
        },
        {
            "name": "Wish List",
            "description": "Wish List"
        }
    ]
}