{
    "openapi": "3.0.0",
    "info": {
        "title": "Loreax API",
        "description": "Loreax creator monetization API.",
        "version": "1.0.0"
    },
    "paths": {
        "/v1/access/purchases": {
            "post": {
                "tags": [
                    "Access"
                ],
                "summary": "Purchase a post",
                "description": "Purchase a post with one-off payment.",
                "operationId": "775970719c93d94ed37a831a689535bb",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "postId"
                                ],
                                "properties": {
                                    "postId": {
                                        "description": "Post ID to purchase",
                                        "type": "integer",
                                        "example": 123
                                    },
                                    "promoCode": {
                                        "description": "Optional promo code for discount",
                                        "type": "string",
                                        "example": "SAVE10",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Purchase successful",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Purchase completed"
                                        },
                                        "data": {
                                            "properties": {
                                                "id": {
                                                    "description": "Purchase ULID",
                                                    "type": "string",
                                                    "example": "01HQ123456789ABCDEFGHJKMNP"
                                                },
                                                "postId": {
                                                    "type": "integer",
                                                    "example": 123
                                                },
                                                "buyerUserId": {
                                                    "type": "integer",
                                                    "example": 456
                                                },
                                                "creatorUserId": {
                                                    "type": "integer",
                                                    "example": 789
                                                },
                                                "grossAmount": {
                                                    "description": "Total price in minor units",
                                                    "type": "integer",
                                                    "example": 10000
                                                },
                                                "platformFee": {
                                                    "description": "Platform fee in minor units",
                                                    "type": "integer",
                                                    "example": 1500
                                                },
                                                "creatorNet": {
                                                    "description": "Creator earnings in minor units",
                                                    "type": "integer",
                                                    "example": 8500
                                                },
                                                "discount": {
                                                    "description": "Discount applied in minor units",
                                                    "type": "integer",
                                                    "example": 0
                                                },
                                                "currency": {
                                                    "type": "string",
                                                    "example": "KES"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "example": "completed"
                                                },
                                                "expiresAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "example": null,
                                                    "nullable": true
                                                },
                                                "purchasedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "example": "2026-04-24T08:00:00Z"
                                                },
                                                "grantsAccess": {
                                                    "type": "boolean",
                                                    "example": true
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "properties": {
                                                "requestId": {
                                                    "type": "string",
                                                    "example": "01HQ123456789ABCDEFGHJKMNP"
                                                },
                                                "traceId": {
                                                    "type": "string",
                                                    "example": "0af7651916cd43dd8448eb211c80319c"
                                                },
                                                "timestamp": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "example": "2026-04-24T08:00:00Z"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ValidationErrorResponse"
                                }
                            }
                        }
                    },
                    "430": {
                        "description": "Business rule violation (already purchased, no purchase rule, insufficient funds)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "errorCode": {
                                            "type": "string",
                                            "enum": [
                                                "POST_ALREADY_PURCHASED",
                                                "ACCESS_RULE_NOT_FOUND",
                                                "INSUFFICIENT_FUNDS"
                                            ]
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "User 456 has already purchased post 123."
                                        },
                                        "meta": {
                                            "properties": {
                                                "requestId": {
                                                    "type": "string"
                                                },
                                                "traceId": {
                                                    "type": "string"
                                                },
                                                "timestamp": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/collections": {
            "post": {
                "tags": [
                    "Content"
                ],
                "summary": "Create a creator collection",
                "operationId": "d65991edd632965c8c18d611158188ed",
                "responses": {
                    "201": {
                        "description": "Collection created"
                    },
                    "409": {
                        "description": "A supplied post does not belong to this creator"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/content/comments/{comment}": {
            "delete": {
                "tags": [
                    "Content"
                ],
                "summary": "Delete own comment",
                "operationId": "312c5059e8d51192fb7d23976cd85743",
                "responses": {
                    "200": {
                        "description": "Comment deleted"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Content"
                ],
                "summary": "Update own comment",
                "operationId": "8ebe5c756b87624e4bf7bbb1e53a405a",
                "responses": {
                    "200": {
                        "description": "Comment updated"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/content/comments/{comment}/pin": {
            "post": {
                "tags": [
                    "Content"
                ],
                "summary": "Pin a comment as the post creator",
                "operationId": "e21f2f30f8c4c6152eb5d063cb7c0a08",
                "responses": {
                    "200": {
                        "description": "Comment pinned"
                    }
                }
            }
        },
        "/v1/posts/{post}/poll/vote": {
            "post": {
                "tags": [
                    "Content"
                ],
                "summary": "Vote on a poll post",
                "operationId": "f270557c1df635a4b0b952f9ecfb5173",
                "responses": {
                    "200": {
                        "description": "Poll vote saved"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/posts/{post}/comments": {
            "get": {
                "tags": [
                    "Content"
                ],
                "summary": "List comments for a post",
                "operationId": "e954f674b8a451be13a8688aabcf4ef7",
                "responses": {
                    "200": {
                        "description": "Comments returned"
                    }
                }
            },
            "post": {
                "tags": [
                    "Content"
                ],
                "summary": "Create a comment",
                "operationId": "4bad184766a3c0e7288e6bcca8fbe17d",
                "responses": {
                    "201": {
                        "description": "Comment created"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/posts": {
            "post": {
                "tags": [
                    "Content"
                ],
                "summary": "Create a draft post",
                "operationId": "eb431f8d7e97e169ff241a327e3320d7",
                "responses": {
                    "201": {
                        "description": "Draft post created"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/posts/{post}": {
            "get": {
                "tags": [
                    "Content"
                ],
                "summary": "Show a post when visible to the current viewer",
                "operationId": "fe10df22dc3d8b41bc2ddb4ebfc9db56",
                "responses": {
                    "200": {
                        "description": "Post returned"
                    },
                    "404": {
                        "description": "Post not found"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Content"
                ],
                "summary": "Delete an owned post",
                "operationId": "be4dcb6d17ba55eec0f05e45e9cade77",
                "responses": {
                    "200": {
                        "description": "Post deleted"
                    },
                    "404": {
                        "description": "Post not found"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Content"
                ],
                "summary": "Edit an owned post",
                "operationId": "08bae407b2fd82858bbc15532b022747",
                "responses": {
                    "200": {
                        "description": "Post updated"
                    },
                    "404": {
                        "description": "Post not found"
                    },
                    "409": {
                        "description": "Post cannot be edited"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/posts/{post}/publish": {
            "post": {
                "tags": [
                    "Content"
                ],
                "summary": "Publish an owned post",
                "operationId": "f31ce950c8f76207516075e552512e93",
                "responses": {
                    "200": {
                        "description": "Post published"
                    },
                    "404": {
                        "description": "Post not found"
                    },
                    "409": {
                        "description": "Post cannot be published"
                    }
                }
            }
        },
        "/v1/posts/{post}/unpublish": {
            "post": {
                "tags": [
                    "Content"
                ],
                "summary": "Unpublish an owned post",
                "operationId": "1573536e6267524b822d8d5c3184be58",
                "responses": {
                    "200": {
                        "description": "Post unpublished"
                    },
                    "404": {
                        "description": "Post not found"
                    },
                    "409": {
                        "description": "Post cannot be unpublished"
                    }
                }
            }
        },
        "/v1/posts/{post}/media": {
            "post": {
                "tags": [
                    "Content"
                ],
                "summary": "Attach media to a draft post",
                "operationId": "db9c68556335a1c4b8cd426c460c3f4e",
                "responses": {
                    "201": {
                        "description": "Post media attached"
                    },
                    "404": {
                        "description": "Post not found"
                    },
                    "409": {
                        "description": "Post cannot be edited"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/taxonomy/niches": {
            "get": {
                "tags": [
                    "Taxonomy"
                ],
                "summary": "List active niches",
                "description": "Returns a list of all active niches (interests/genres) available on the platform.",
                "operationId": "5db359a8cda12e8ac89cc10082155c0d",
                "responses": {
                    "200": {
                        "description": "List of active niches",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Success"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "id": {
                                                        "description": "Public ULID",
                                                        "type": "string",
                                                        "example": "01HQ123456789ABCDEFGHJKMNP"
                                                    },
                                                    "name": {
                                                        "type": "string",
                                                        "example": "Technology"
                                                    },
                                                    "slug": {
                                                        "type": "string",
                                                        "example": "technology"
                                                    },
                                                    "description": {
                                                        "type": "string",
                                                        "example": "Tech, gadgets, software, and innovation",
                                                        "nullable": true
                                                    },
                                                    "isActive": {
                                                        "type": "boolean",
                                                        "example": true
                                                    },
                                                    "sortOrder": {
                                                        "type": "integer",
                                                        "example": 1
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/taxonomy/categories": {
            "get": {
                "tags": [
                    "Taxonomy"
                ],
                "summary": "List active categories",
                "description": "Returns a list of all active categories, optionally filtered by niche.",
                "operationId": "06e40a4c3eabe2c2e60f07417f4b5012",
                "parameters": [
                    {
                        "name": "nicheId",
                        "in": "query",
                        "description": "Filter categories by niche ID",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "01HQ123456789ABCDEFGHJKMNP"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of active categories",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Success"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "id": {
                                                        "description": "Public ULID",
                                                        "type": "string",
                                                        "example": "01HQ234567890BCDEFGHJKMNPQ"
                                                    },
                                                    "nicheId": {
                                                        "type": "string",
                                                        "example": "01HQ123456789ABCDEFGHJKMNP",
                                                        "nullable": true
                                                    },
                                                    "name": {
                                                        "type": "string",
                                                        "example": "Web Development"
                                                    },
                                                    "slug": {
                                                        "type": "string",
                                                        "example": "web-development"
                                                    },
                                                    "description": {
                                                        "type": "string",
                                                        "example": "Frontend, backend, and full-stack development",
                                                        "nullable": true
                                                    },
                                                    "isActive": {
                                                        "type": "boolean",
                                                        "example": true
                                                    },
                                                    "sortOrder": {
                                                        "type": "integer",
                                                        "example": 1
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/taxonomy/tags": {
            "get": {
                "tags": [
                    "Taxonomy"
                ],
                "summary": "Search active tags",
                "description": "Search for active tags by prefix. Returns tags matching the search term.",
                "operationId": "b586cb3217e31807b63c3caa69b06d5d",
                "parameters": [
                    {
                        "name": "prefix",
                        "in": "query",
                        "description": "Search prefix for tag names",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "java"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of matching tags",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Success"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "id": {
                                                        "description": "Public ULID",
                                                        "type": "string",
                                                        "example": "01HQ345678901CDEFGHJKMNPQR"
                                                    },
                                                    "name": {
                                                        "type": "string",
                                                        "example": "javascript"
                                                    },
                                                    "slug": {
                                                        "type": "string",
                                                        "example": "javascript"
                                                    },
                                                    "useCount": {
                                                        "description": "Number of posts using this tag",
                                                        "type": "integer",
                                                        "example": 42
                                                    },
                                                    "isActive": {
                                                        "type": "boolean",
                                                        "example": true
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/": {
            "get": {
                "tags": [
                    "Core"
                ],
                "summary": "Get API root information",
                "description": "Returns API version, documentation links, and service status",
                "operationId": "d6e50febb5ed3ca1bd7a6a5b4a309b96",
                "responses": {
                    "200": {
                        "description": "API information",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Loreax v1 APIs"
                                        },
                                        "data": {
                                            "properties": {
                                                "version": {
                                                    "type": "string",
                                                    "example": "v1"
                                                },
                                                "docs": {
                                                    "properties": {
                                                        "wiki": {
                                                            "type": "string",
                                                            "example": "https://dev.loreax.bervant.co.ke"
                                                        },
                                                        "openapi": {
                                                            "properties": {
                                                                "schema": {
                                                                    "type": "string",
                                                                    "example": "https://dev.loreax.bervant.co.ke/api-reference"
                                                                },
                                                                "json": {
                                                                    "type": "string",
                                                                    "example": "https://dev.loreax.bervant.co.ke/api-reference/download/openapi"
                                                                },
                                                                "postman": {
                                                                    "type": "string",
                                                                    "example": "https://dev.loreax.bervant.co.ke/api-reference/download/postman"
                                                                },
                                                                "bruno": {
                                                                    "type": "string",
                                                                    "example": "https://dev.loreax.bervant.co.ke/api-reference/download/bruno"
                                                                }
                                                            },
                                                            "type": "object"
                                                        },
                                                        "interactive": {
                                                            "type": "string",
                                                            "example": "https://dev.loreax.bervant.co.ke/api-playground"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "services": {
                                                    "type": "object",
                                                    "example": {
                                                        "postgres": {
                                                            "status": "ok",
                                                            "latency_ms": 12
                                                        },
                                                        "redis": {
                                                            "status": "ok",
                                                            "latency_ms": 2
                                                        },
                                                        "mongodb": {
                                                            "status": "ok",
                                                            "latency_ms": 1
                                                        },
                                                        "s3": {
                                                            "status": "error",
                                                            "message": "Unable to check existence"
                                                        },
                                                        "mpesa": {
                                                            "status": "ok",
                                                            "latency_ms": 494,
                                                            "cached": false
                                                        }
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "properties": {
                                                "requestId": {
                                                    "type": "string",
                                                    "example": "01HQ123456789ABCDEFGHJKMNP"
                                                },
                                                "traceId": {
                                                    "type": "string",
                                                    "example": "0af7651916cd43dd8448eb211c80319c"
                                                },
                                                "timestamp": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "example": "2026-04-27T10:00:00Z"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/discovery/creators": {
            "get": {
                "tags": [
                    "Discovery"
                ],
                "summary": "Browse public creators",
                "operationId": "55272acae0334e03de5c81281844a53e",
                "parameters": [
                    {
                        "name": "niche",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "verified",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 50,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Cursor-paginated creator browse results"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/discovery/interactions": {
            "post": {
                "tags": [
                    "Discovery"
                ],
                "summary": "Log discovery interaction batch",
                "operationId": "4aa04be6c060349e66598c8f429fb989",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "interactions"
                                ],
                                "properties": {
                                    "interactions": {
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "targetType",
                                                "targetId",
                                                "type"
                                            ],
                                            "properties": {
                                                "targetType": {
                                                    "type": "string",
                                                    "enum": [
                                                        "post",
                                                        "creator",
                                                        "collection",
                                                        "tag"
                                                    ]
                                                },
                                                "targetId": {
                                                    "type": "string"
                                                },
                                                "type": {
                                                    "type": "string",
                                                    "enum": [
                                                        "impression",
                                                        "click",
                                                        "dwell",
                                                        "like",
                                                        "unlike",
                                                        "comment",
                                                        "share",
                                                        "save",
                                                        "unsave",
                                                        "purchase",
                                                        "subscribe",
                                                        "skip",
                                                        "report"
                                                    ]
                                                },
                                                "surface": {
                                                    "type": "string",
                                                    "enum": [
                                                        "home",
                                                        "explore",
                                                        "trending",
                                                        "search",
                                                        "creator_profile"
                                                    ]
                                                },
                                                "position": {
                                                    "type": "integer"
                                                },
                                                "occurredAt": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "context": {
                                                    "type": "object"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Interactions accepted"
                    },
                    "401": {
                        "description": "Unauthenticated"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                },
                "security": [
                    {
                        "sanctum": []
                    }
                ]
            }
        },
        "/v1/discovery/search": {
            "get": {
                "tags": [
                    "Discovery"
                ],
                "summary": "Search posts, creators, collections, and tags",
                "operationId": "ded152df1f0c0906105350b80c0248ce",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 120,
                            "minLength": 2
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "post",
                                "creator",
                                "collection",
                                "tag",
                                "all"
                            ]
                        }
                    },
                    {
                        "name": "niche",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "tag",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 50,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Ranked search results"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/timeline/home": {
            "get": {
                "tags": [
                    "Timeline"
                ],
                "summary": "Get personalized home timeline",
                "operationId": "4ef7affb58ec026d574dc67ec4e85d60",
                "parameters": [
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 50,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Ranked home timeline"
                    },
                    "401": {
                        "description": "Unauthenticated"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                },
                "security": [
                    {
                        "sanctum": []
                    }
                ]
            }
        },
        "/v1/timeline/explore": {
            "get": {
                "tags": [
                    "Timeline"
                ],
                "summary": "Get explore timeline",
                "operationId": "70a64b4ff4cf879e6fb6b2fed7633b1e",
                "parameters": [
                    {
                        "name": "niche",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "tag",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "creator",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 50,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Ranked explore timeline"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/timeline/trending": {
            "get": {
                "tags": [
                    "Timeline"
                ],
                "summary": "Get trending timeline",
                "operationId": "4b3d2bbbeb7542f13c3aaa3ddbd44db3",
                "parameters": [
                    {
                        "name": "niche",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "tag",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 50,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Ranked trending timeline"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/auth/login": {
            "post": {
                "tags": [
                    "Identity"
                ],
                "summary": "Authenticate and receive access token",
                "operationId": "261dd411dd9934f473513f05330cb7c8",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "username",
                                    "password"
                                ],
                                "properties": {
                                    "username": {
                                        "description": "Username or email address",
                                        "type": "string"
                                    },
                                    "password": {
                                        "type": "string",
                                        "format": "password"
                                    },
                                    "deviceName": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Authenticated"
                    },
                    "401": {
                        "description": "Invalid credentials"
                    },
                    "422": {
                        "description": "Validation error"
                    },
                    "429": {
                        "description": "Rate limited"
                    }
                }
            }
        },
        "/v1/auth/logout": {
            "post": {
                "tags": [
                    "Identity"
                ],
                "summary": "Revoke the current access token",
                "operationId": "bf3afb262d61e21264a5c453256bf853",
                "responses": {
                    "204": {
                        "description": "Logged out"
                    }
                },
                "security": [
                    {
                        "sanctum": []
                    }
                ]
            }
        },
        "/v1/auth/register": {
            "post": {
                "tags": [
                    "Identity"
                ],
                "summary": "Register a new user account",
                "operationId": "8a6893655c4509fb7f8c0ce9c5b0bcb4",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email",
                                    "username",
                                    "password",
                                    "firstName",
                                    "lastName"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "username": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "minLength": 3
                                    },
                                    "password": {
                                        "type": "string",
                                        "format": "password",
                                        "minLength": 8
                                    },
                                    "firstName": {
                                        "type": "string"
                                    },
                                    "lastName": {
                                        "type": "string"
                                    },
                                    "countryCode": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "referralCode": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "User registered"
                    },
                    "422": {
                        "description": "Validation error"
                    },
                    "430": {
                        "description": "EMAIL_ALREADY_REGISTERED or USERNAME_UNAVAILABLE"
                    }
                }
            }
        },
        "/v1/monetization/premium": {
            "get": {
                "tags": [
                    "Monetization"
                ],
                "summary": "Show current premium subscription",
                "operationId": "cb8de067c8dbe6dbcdfd6bc416d7115a",
                "responses": {
                    "200": {
                        "description": "Premium status"
                    }
                }
            },
            "post": {
                "tags": [
                    "Monetization"
                ],
                "summary": "Start premium subscription",
                "operationId": "3a446f81759f94dcaec1484003df2a3a",
                "responses": {
                    "201": {
                        "description": "Premium started"
                    },
                    "430": {
                        "description": "Business rule violation"
                    }
                }
            }
        },
        "/v1/monetization/premium/cancel": {
            "post": {
                "tags": [
                    "Monetization"
                ],
                "summary": "Cancel premium at period end",
                "operationId": "7af0aa83110a7c5460afe94dae849dfa",
                "responses": {
                    "200": {
                        "description": "Premium cancellation scheduled"
                    }
                }
            }
        },
        "/v1/creators/{creator}/tiers": {
            "get": {
                "tags": [
                    "Monetization"
                ],
                "summary": "List a creator active tiers",
                "operationId": "57a2acadad3db44b4af485e464693557",
                "responses": {
                    "200": {
                        "description": "Creator tiers listed"
                    }
                }
            }
        },
        "/v1/monetization/tiers": {
            "post": {
                "tags": [
                    "Monetization"
                ],
                "summary": "Create a creator tier",
                "operationId": "b9cff0c0da22431fb359b3e3bbc276ea",
                "responses": {
                    "201": {
                        "description": "Tier created"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/monetization/tiers/{tier}": {
            "patch": {
                "tags": [
                    "Monetization"
                ],
                "summary": "Update an owned creator tier",
                "operationId": "c389242543d8678893a34635bfa65d20",
                "responses": {
                    "200": {
                        "description": "Tier updated"
                    },
                    "404": {
                        "description": "Tier not found"
                    }
                }
            }
        },
        "/v1/monetization/tiers/{tier}/archive": {
            "post": {
                "tags": [
                    "Monetization"
                ],
                "summary": "Archive an owned creator tier",
                "operationId": "c2bcf9617570a0d020d5bfcad5aba0b7",
                "responses": {
                    "200": {
                        "description": "Tier archived"
                    }
                }
            }
        },
        "/v1/monetization/tier-subscriptions": {
            "get": {
                "tags": [
                    "Monetization"
                ],
                "summary": "List own tier subscriptions",
                "operationId": "cd870c30b2e079c171baac3d04aa4ce2",
                "responses": {
                    "200": {
                        "description": "Subscriptions listed"
                    }
                }
            },
            "post": {
                "tags": [
                    "Monetization"
                ],
                "summary": "Subscribe to a tier",
                "operationId": "f597bc2457d273ddc6c114928e40a940",
                "responses": {
                    "201": {
                        "description": "Subscription created"
                    },
                    "430": {
                        "description": "Business rule violation"
                    }
                }
            }
        },
        "/v1/monetization/tier-subscriptions/{subscription}/cancel": {
            "post": {
                "tags": [
                    "Monetization"
                ],
                "summary": "Cancel a tier subscription at period end",
                "operationId": "84c9a0b2e01c3f7bdf8679addafe86a4",
                "responses": {
                    "200": {
                        "description": "Subscription cancellation scheduled"
                    }
                }
            }
        },
        "/v1/monetization/tier-subscriptions/{subscription}/resume": {
            "post": {
                "tags": [
                    "Monetization"
                ],
                "summary": "Resume a tier subscription",
                "operationId": "330f143a9918331c88886601a3aee234",
                "responses": {
                    "200": {
                        "description": "Subscription resumed"
                    }
                }
            }
        },
        "/v1/monetization/verification-requests": {
            "get": {
                "tags": [
                    "Monetization"
                ],
                "summary": "List own verification requests",
                "operationId": "673a7b8e7aecc3da09ad50063cd27862",
                "responses": {
                    "200": {
                        "description": "Verification requests listed"
                    }
                }
            },
            "post": {
                "tags": [
                    "Monetization"
                ],
                "summary": "Submit a notable verification request",
                "operationId": "89b50dc596c19906ec89fc5ca2b7a3e7",
                "responses": {
                    "201": {
                        "description": "Verification request submitted"
                    }
                }
            }
        },
        "/v1/payments/withdrawals": {
            "get": {
                "tags": [
                    "Payments"
                ],
                "summary": "List own withdrawals",
                "operationId": "ebdefa0b4891042c71eac16c7ec9f3ae",
                "responses": {
                    "200": {
                        "description": "Withdrawals listed"
                    }
                }
            },
            "post": {
                "tags": [
                    "Payments"
                ],
                "summary": "Request a withdrawal",
                "operationId": "1b461036ae41756a16d1a1578049fb7a",
                "responses": {
                    "201": {
                        "description": "Withdrawal request created"
                    },
                    "422": {
                        "description": "Validation error"
                    },
                    "430": {
                        "description": "Business rule violation"
                    }
                }
            }
        },
        "/v1/payments/withdrawals/{withdrawal}": {
            "get": {
                "tags": [
                    "Payments"
                ],
                "summary": "Show a withdrawal",
                "operationId": "897be7a7dc656e50d449044cd0552df9",
                "responses": {
                    "200": {
                        "description": "Withdrawal details"
                    },
                    "404": {
                        "description": "Not found"
                    }
                }
            }
        },
        "/v1/payments/withdrawal-methods": {
            "get": {
                "tags": [
                    "Payments"
                ],
                "summary": "List own withdrawal methods",
                "operationId": "f1a901c22f558ba74c2bcd2bc7b43c4b",
                "responses": {
                    "200": {
                        "description": "Withdrawal methods listed"
                    }
                }
            },
            "post": {
                "tags": [
                    "Payments"
                ],
                "summary": "Add a withdrawal method",
                "operationId": "925eccb3e8d7cd13a2b3209a1c3140df",
                "responses": {
                    "201": {
                        "description": "Withdrawal method created"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/fanclubs": {
            "get": {
                "tags": [
                    "Social"
                ],
                "summary": "List fan clubs the authenticated user belongs to",
                "operationId": "98b67af0f573634620a60d64f298de22",
                "responses": {
                    "200": {
                        "description": "Fan clubs returned"
                    }
                }
            },
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Create the authenticated creator fan club",
                "operationId": "209d194272f37d721dbc13c23b6793ec",
                "responses": {
                    "201": {
                        "description": "Fan club created"
                    },
                    "422": {
                        "description": "Validation error"
                    },
                    "403": {
                        "description": "Creator required"
                    }
                }
            }
        },
        "/v1/fanclubs/{id}": {
            "get": {
                "tags": [
                    "Social"
                ],
                "summary": "Show fan club details",
                "operationId": "e489752557580cf186f36a5147163330",
                "responses": {
                    "200": {
                        "description": "Fan club returned"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Social"
                ],
                "summary": "Update fan club metadata",
                "operationId": "07ac42e014e0172b5091f25e5a7e86fc",
                "responses": {
                    "200": {
                        "description": "Fan club updated"
                    },
                    "422": {
                        "description": "Validation error"
                    },
                    "403": {
                        "description": "Creator required"
                    }
                }
            }
        },
        "/v1/fanclubs/{id}/join": {
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Join a fan club when qualified",
                "operationId": "9084290df7254c7ed41d2ba77761ba37",
                "responses": {
                    "201": {
                        "description": "Membership created"
                    },
                    "403": {
                        "description": "Membership requirements not met"
                    }
                }
            }
        },
        "/v1/fanclubs/{id}/channels": {
            "get": {
                "tags": [
                    "Social"
                ],
                "summary": "List fan club channels",
                "operationId": "74458a68d660d6d5d679a09fa497be5f",
                "responses": {
                    "200": {
                        "description": "Channels returned"
                    }
                }
            },
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Create a fan club channel",
                "operationId": "a4f9b312ffb88088a8caaacd647157a4",
                "responses": {
                    "201": {
                        "description": "Channel created"
                    },
                    "422": {
                        "description": "Validation error"
                    },
                    "403": {
                        "description": "Creator required"
                    }
                }
            }
        },
        "/v1/fanclubs/{id}/members": {
            "get": {
                "tags": [
                    "Social"
                ],
                "summary": "List fan club members",
                "operationId": "339781374fcb80dbdfb0ccebab68b651",
                "responses": {
                    "200": {
                        "description": "Members returned"
                    }
                }
            }
        },
        "/v1/fanclubs/{id}/timeout-user": {
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Timeout a fan club member",
                "operationId": "27aa414030d187ed8613dda9ae440d17",
                "responses": {
                    "201": {
                        "description": "Timeout created"
                    },
                    "422": {
                        "description": "Validation error"
                    },
                    "403": {
                        "description": "Moderator required"
                    }
                }
            }
        },
        "/v1/fanclubs/{id}/channels/{slug}/messages": {
            "get": {
                "tags": [
                    "Social"
                ],
                "summary": "List historical fan club messages",
                "operationId": "320d8a348e85819f932fe8ba8ec2d7e9",
                "responses": {
                    "200": {
                        "description": "Messages returned"
                    }
                }
            },
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Post a fan club message",
                "operationId": "c7d309f662dcd2c76cc3174d61b8cce4",
                "responses": {
                    "201": {
                        "description": "Message posted"
                    },
                    "422": {
                        "description": "Validation error"
                    },
                    "403": {
                        "description": "Membership or channel access required"
                    }
                }
            }
        },
        "/v1/fanclubs/{id}/channels/{slug}/stream": {
            "get": {
                "tags": [
                    "Social"
                ],
                "summary": "Open fan club message stream",
                "operationId": "fa4c6e7966eabdebf9e3d36000709903",
                "responses": {
                    "200": {
                        "description": "SSE stream opened"
                    }
                }
            }
        },
        "/v1/fanclubs/{id}/messages/{msgId}/pin": {
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Pin a fan club message",
                "operationId": "d13f16ffd25a8be0116058b12f5e5d71",
                "responses": {
                    "200": {
                        "description": "Message pinned"
                    },
                    "403": {
                        "description": "Moderator required"
                    }
                }
            }
        },
        "/v1/fanclubs/{id}/messages/{msgId}/delete": {
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Delete a fan club message",
                "operationId": "760c0d0dd8a57a938a84a8b2847f5c9f",
                "responses": {
                    "200": {
                        "description": "Message deleted"
                    },
                    "422": {
                        "description": "Validation error"
                    },
                    "403": {
                        "description": "Moderator required"
                    }
                }
            }
        },
        "/v1/social/follow/{userId}": {
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Follow a user",
                "operationId": "b82f6fef6313b8148f6fb8062f43b367",
                "responses": {
                    "201": {
                        "description": "Follow edge created or already present"
                    },
                    "430": {
                        "description": "Business rule violation"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Social"
                ],
                "summary": "Unfollow a user",
                "operationId": "982541cb02bbb768b929b95931e70fdf",
                "responses": {
                    "200": {
                        "description": "Follow edge removed or already absent"
                    }
                }
            }
        },
        "/v1/users/{id}/followers": {
            "get": {
                "tags": [
                    "Social"
                ],
                "summary": "List user followers",
                "operationId": "6cebec174420a2fa045670378a978f20",
                "responses": {
                    "200": {
                        "description": "Followers returned"
                    }
                }
            }
        },
        "/v1/users/{id}/following": {
            "get": {
                "tags": [
                    "Social"
                ],
                "summary": "List users followed by a user",
                "operationId": "f7d805fa7c60b36164c8e0d962118fd3",
                "responses": {
                    "200": {
                        "description": "Following returned"
                    }
                }
            }
        },
        "/v1/social/lists": {
            "get": {
                "tags": [
                    "Social"
                ],
                "summary": "List own creator lists",
                "operationId": "9a0f55e45639b2fc8482f7e023a81f8e",
                "responses": {
                    "200": {
                        "description": "Lists returned"
                    }
                }
            },
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Create a creator list",
                "operationId": "94eb6323ee6d6958e401681907e61bfd",
                "responses": {
                    "201": {
                        "description": "List created"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/social/lists/{id}": {
            "get": {
                "tags": [
                    "Social"
                ],
                "summary": "View a public or owned creator list",
                "operationId": "e7900c63e93043dcdfb1aa77c14e4a4e",
                "responses": {
                    "200": {
                        "description": "List returned"
                    },
                    "404": {
                        "description": "List not found"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Social"
                ],
                "summary": "Delete an owned creator list",
                "operationId": "76f20d0018d931acfe1ea896edc256cd",
                "responses": {
                    "200": {
                        "description": "List deleted"
                    },
                    "403": {
                        "description": "Ownership required"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Social"
                ],
                "summary": "Update an owned creator list",
                "operationId": "f50879d7ec8285cd1450b06cea212b7f",
                "responses": {
                    "200": {
                        "description": "List updated"
                    },
                    "403": {
                        "description": "Ownership required"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/social/lists/{id}/members/{userId}": {
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Add a member to an owned creator list",
                "operationId": "f07782f71a4f74e30b1e8195a7608940",
                "responses": {
                    "200": {
                        "description": "Member added"
                    },
                    "403": {
                        "description": "Ownership required"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Social"
                ],
                "summary": "Remove a member from an owned creator list",
                "operationId": "a3b1233524a3f07829fa8d5bf7b5d870",
                "responses": {
                    "200": {
                        "description": "Member removed"
                    },
                    "403": {
                        "description": "Ownership required"
                    }
                }
            }
        },
        "/v1/social/posts/{id}/like": {
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Like a post",
                "operationId": "66f88ca95a0219536bee055a265680d9",
                "responses": {
                    "201": {
                        "description": "Post liked"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Social"
                ],
                "summary": "Unlike a post",
                "operationId": "f3e472e1692d7bbd060d6d55edcfa3a2",
                "responses": {
                    "200": {
                        "description": "Post unliked"
                    }
                }
            }
        },
        "/v1/social/posts/{id}/share": {
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Track a post share",
                "operationId": "237328e7797e29d6a9b96e2bfc642d00",
                "responses": {
                    "201": {
                        "description": "Share tracked"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v1/social/posts/{id}/save": {
            "post": {
                "tags": [
                    "Social"
                ],
                "summary": "Save a post",
                "operationId": "ccdcd33e8d8b9bd1955a6df7de91176c",
                "responses": {
                    "201": {
                        "description": "Post saved"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Social"
                ],
                "summary": "Unsave a post",
                "operationId": "8d8cd3c134b3ea70e78b4811fc40b0eb",
                "responses": {
                    "200": {
                        "description": "Post unsaved"
                    }
                }
            }
        },
        "/v1/social/saves": {
            "get": {
                "tags": [
                    "Social"
                ],
                "summary": "List own saved posts",
                "operationId": "bbdb56c17c40d7b94b3ba41d8f444b16",
                "responses": {
                    "200": {
                        "description": "Saved posts returned"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "ValidationErrorResponse": {
                "required": [
                    "message",
                    "errors",
                    "meta"
                ],
                "properties": {
                    "message": {
                        "type": "string",
                        "example": "Invalid input"
                    },
                    "errors": {
                        "type": "object"
                    },
                    "meta": {
                        "type": "object"
                    }
                },
                "type": "object"
            }
        },
        "securitySchemes": {
            "sanctum": {
                "type": "http",
                "bearerFormat": "Sanctum",
                "scheme": "bearer"
            }
        }
    },
    "tags": [
        {
            "name": "Access",
            "description": "Access"
        },
        {
            "name": "Content",
            "description": "Content"
        },
        {
            "name": "Taxonomy",
            "description": "Taxonomy"
        },
        {
            "name": "Core",
            "description": "Core"
        },
        {
            "name": "Discovery",
            "description": "Discovery"
        },
        {
            "name": "Timeline",
            "description": "Timeline"
        },
        {
            "name": "Identity",
            "description": "Identity"
        },
        {
            "name": "Monetization",
            "description": "Monetization"
        },
        {
            "name": "Payments",
            "description": "Payments"
        },
        {
            "name": "Social",
            "description": "Social"
        }
    ],
    "servers": [
        {
            "url": "https://api.loreax.bervant.co.ke",
            "description": "Hyena API Server"
        }
    ]
}