{
  "openapi": "3.1.1",
  "info": {
    "title": "ForumSDK API v1",
    "version": "1.9.9",
    "contact": {
      "name": "ForumSDK",
      "url": "https://forumsdk.com"
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the user."
          },
          "username": {
            "type": "string",
            "description": "The username of the user."
          },
          "email": {
            "type": "string",
            "description": "The email of the user."
          },
          "displayName": {
            "type": "string",
            "description": "The display name of the user."
          },
          "password": {
            "type": "string",
            "format": "password",
            "description": "The password of the user."
          },
          "emailVerified": {
            "type": "boolean",
            "description": "Indicates if the email of the user is verified."
          },
          "roles": {
            "type": "array",
            "description": "The roles of the user.",
            "items": {
              "type": "string"
            }
          },
          "bio": {
            "type": "string",
            "description": "The bio of the user."
          },
          "signature": {
            "type": "string",
            "description": "The signature of the user."
          },
          "url": {
            "type": "string",
            "description": "The URL of the user."
          },
          "postsCount": {
            "type": "integer",
            "description": "The total number of posts created by the user.",
            "readOnly": true
          },
          "threadsCount": {
            "type": "integer",
            "description": "The total number of threads created by the user.",
            "readOnly": true
          },
          "extendedData": {
            "type": "object",
            "description": "The extended data of the user."
          }
        }
      },
      "Follow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the follower."
          },
          "followerId": {
            "type": "string",
            "description": "The ID of the follower."
          },
          "followingId": {
            "type": "string",
            "description": "The ID of the user being followed."
          },
          "extendedData": {
            "type": "object",
            "description": "The extended data of the follower."
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the follower was created."
          },
          "updatedAt": {
            "type": "string",
            "description": "The date when the follower was updated."
          }
        }
      },
      "Tag": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the tag."
          },
          "name": {
            "type": "string",
            "description": "The name of the tag."
          },
          "description": {
            "type": "string",
            "description": "The description of the tag."
          },
          "color": {
            "type": "string",
            "description": "The color of the tag."
          },
          "threads": {
            "type": "array",
            "description": "The threads of the tag.",
            "items": {
              "$ref": "#/components/schemas/Thread"
            }
          },
          "extendedData": {
            "type": "object",
            "description": "The extended data of the tag."
          }
        }
      },
      "Thread": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the thread."
          },
          "title": {
            "type": "string",
            "description": "The title of the thread."
          },
          "slug": {
            "type": "string",
            "description": "The slug of the thread."
          },
          "body": {
            "type": "string",
            "description": "The content of the thread."
          },
          "locked": {
            "type": "boolean",
            "description": "Indicates if the thread is locked."
          },
          "pinned": {
            "type": "boolean",
            "description": "Indicates if the thread is pinned."
          },
          "user": {
            "type": "object",
            "description": "The user who created the thread.",
            "properties": {
              "id": {
                "type": "string",
                "description": "The ID of the user."
              },
              "username": {
                "type": "string",
                "description": "The username of the user."
              }
            }
          },
          "tags": {
            "type": "array",
            "description": "The tags of the thread.",
            "items": {
              "$ref": "#/components/schemas/Tag"
            }
          },
          "postsCount": {
            "type": "integer",
            "description": "The total number of posts in the thread.",
            "readOnly": true
          },
          "lastPostAt": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time when the last post was made in the thread.",
            "readOnly": true
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the thread was created."
          },
          "updatedAt": {
            "type": "string",
            "description": "The date when the thread was updated."
          }
        }
      },
      "Like": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the like."
          },
          "userId": {
            "type": "string",
            "description": "The ID of the user who liked the thread."
          },
          "threadId": {
            "type": "string",
            "description": "The ID of the thread."
          },
          "postId": {
            "type": "string",
            "description": "The ID of the post."
          },
          "dislike": {
            "type": "boolean",
            "description": "Indicates if the like is a dislike."
          },
          "extendedData": {
            "type": "object",
            "description": "The extended data of the like."
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the like was created."
          },
          "updatedAt": {
            "type": "string",
            "description": "The date when the like was updated."
          }
        }
      },
      "Upvote": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the upvote."
          },
          "userId": {
            "type": "string",
            "description": "The ID of the user who upvoted the thread."
          },
          "threadId": {
            "type": "string",
            "description": "The ID of the thread."
          },
          "postId": {
            "type": "string",
            "description": "The ID of the post."
          },
          "downvote": {
            "type": "boolean",
            "description": "Indicates if the upvote is a downvote."
          },
          "extendedData": {
            "type": "object",
            "description": "The extended data of the upvote."
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the upvote was created."
          },
          "updatedAt": {
            "type": "string",
            "description": "The date when the upvote was updated."
          }
        }
      },
      "Poll": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the poll."
          },
          "title": {
            "type": "string",
            "description": "The title of the poll."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "The expiration date and time of the poll."
          },
          "closed": {
            "type": "boolean",
            "description": "Indicates if the poll is closed."
          },
          "closedAt": {
            "type": "string",
            "format": "date-time",
            "description": "The closed date and time of the poll."
          },
          "options": {
            "type": "array",
            "description": "The options for the poll.",
            "items": {
              "$ref": "#/components/schemas/PollOption"
            }
          },
          "extendedData": {
            "type": "object",
            "description": "The additional data for the poll."
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the poll was created."
          },
          "updatedAt": {
            "type": "string",
            "description": "The date when the poll was updated."
          }
        }
      },
      "Post": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the post."
          },
          "body": {
            "type": "string",
            "description": "The content of the post."
          },
          "userId": {
            "type": "string",
            "description": "The ID of the user who created the post.",
            "readOnly": true
          },
          "threadId": {
            "type": "string",
            "description": "The ID of the thread to which the post belongs."
          },
          "parentId": {
            "type": "string",
            "description": "The ID of the parent post."
          },
          "likes": {
            "type": "array",
            "description": "The likes received by the post.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The ID of the like."
                },
                "userId": {
                  "type": "string",
                  "description": "The ID of the user who liked the post."
                }
              }
            }
          },
          "upvotes": {
            "type": "array",
            "description": "The upvotes received by the post.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The ID of the upvote."
                },
                "userId": {
                  "type": "string",
                  "description": "The ID of the user who upvoted the post."
                }
              }
            }
          },
          "extendedData": {
            "type": "object",
            "description": "The extended data of the post."
          },
          "instanceId": {
            "type": "string",
            "description": "The ID of the instance to which the post belongs."
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the post was created."
          },
          "updatedAt": {
            "type": "string",
            "description": "The date when the post was updated."
          }
        }
      },
      "Report": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the report."
          },
          "reportedId": {
            "type": "string",
            "description": "The ID of the user being reported."
          },
          "reporterId": {
            "type": "string",
            "description": "The ID of the user who is reporting."
          },
          "threadId": {
            "type": "string",
            "description": "The ID of the reported thread."
          },
          "postId": {
            "type": "string",
            "description": "The ID of the post being reported."
          },
          "privateMessageId": {
            "type": "string",
            "description": "The ID of the reported private message."
          },
          "status": {
            "type": "string",
            "description": "The status of the report (e.g. pending, in_review, resolved, dismissed, escalated)."
          },
          "type": {
            "type": "string",
            "description": "The type of the report."
          },
          "description": {
            "type": "string",
            "description": "The description of the report."
          },
          "instanceId": {
            "type": "string",
            "description": "The ID of the instance."
          },
          "extendedData": {
            "type": "object",
            "description": "Additional data related to the report."
          }
        }
      },
      "ThreadSubscription": {
        "type": "object",
        "properties": {
          "threadId": {
            "type": "string",
            "description": "The ID of the subscribed thread."
          },
          "userId": {
            "type": "string",
            "description": "The ID of the user who subscribed to the thread."
          },
          "instanceId": {
            "type": "string",
            "description": "The ID of the instance associated with the subscription."
          },
          "extendedData": {
            "type": "object",
            "description": "Optional extended data associated with the subscription."
          }
        }
      },
      "PollOption": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "pollId": {
            "type": "string"
          },
          "votes": {
            "type": "array",
            "description": "Array of votes for this poll option",
            "items": {
              "$ref": "#/components/schemas/PollVote"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PollVote": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "pollId": {
            "type": "string"
          },
          "optionId": {
            "type": "string"
          },
          "userId": {
            "type": "string"
          },
          "instanceId": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "user": {
            "$ref": "#/components/schemas/User",
            "description": "The user who cast this vote"
          }
        }
      },
      "PollResults": {
        "type": "object",
        "properties": {
          "options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PollOptionResult"
            }
          },
          "userVote": {
            "type": "string",
            "nullable": true,
            "description": "The option ID that the user voted for, or null if they haven't voted"
          }
        }
      },
      "PollOptionResult": {
        "type": "object",
        "description": "Simplified poll option with vote count (used in results endpoint)",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the poll option"
          },
          "title": {
            "type": "string",
            "description": "The title of the poll option"
          },
          "color": {
            "type": "string",
            "description": "The color of the poll option"
          },
          "votes": {
            "type": "integer",
            "description": "The number of votes this option received"
          }
        }
      },
      "Role": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the role."
          },
          "name": {
            "type": "string",
            "description": "The name of the role."
          },
          "description": {
            "type": "string",
            "description": "The description of the role."
          },
          "color": {
            "type": "string",
            "description": "The color of the role."
          },
          "extendedData": {
            "type": "object",
            "description": "The extended data of the role."
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the role was created."
          },
          "updatedAt": {
            "type": "string",
            "description": "The date when the role was updated."
          }
        }
      },
      "Notification": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the notification."
          },
          "notifiedId": {
            "type": "string",
            "description": "The ID of the user who received the notification."
          },
          "type": {
            "type": "string",
            "description": "The type of the notification."
          },
          "status": {
            "type": "string",
            "description": "The status of the notification (e.g. read, unread, dismissed, archived, failed, draft)."
          },
          "extendedData": {
            "type": "object",
            "description": "Additional data related to the notification."
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the notification was created."
          },
          "updatedAt": {
            "type": "string",
            "description": "The date when the notification was updated."
          }
        }
      },
      "PrivateMessage": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the private message.",
            "readOnly": true
          },
          "title": {
            "type": "string",
            "description": "The title of the private message."
          },
          "body": {
            "type": "string",
            "description": "The content of the private message."
          },
          "senderId": {
            "type": "string",
            "description": "The ID of the user who sent the private message.",
            "readOnly": true
          },
          "recipientId": {
            "type": "string",
            "description": "The ID of the user who received the private message."
          },
          "status": {
            "type": "string",
            "description": "The status of the private message (e.g. sent, delivered, read, archived).",
            "readOnly": true
          },
          "extendedData": {
            "type": "object",
            "description": "Additional data related to the private message."
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the private message was created.",
            "readOnly": true
          },
          "updatedAt": {
            "type": "string",
            "description": "The date when the private message was updated.",
            "readOnly": true
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": [
          "message",
          "statusCode"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable error message"
          },
          "statusCode": {
            "type": "integer",
            "description": "HTTP status code"
          },
          "errors": {
            "type": "array",
            "description": "Detailed validation errors (optional)",
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            }
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "required": [
          "field",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Field that failed validation"
          },
          "message": {
            "type": "string",
            "description": "Validation error message"
          }
        }
      },
      "SSOProvider": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the SSO provider."
          },
          "provider": {
            "type": "string",
            "enum": [
              "OKTA",
              "AUTH0",
              "SAML"
            ],
            "description": "The type of the SSO provider."
          },
          "domain": {
            "type": "string",
            "description": "The email domain associated with the provider."
          },
          "config": {
            "type": "object",
            "description": "The SSO configuration."
          },
          "active": {
            "type": "boolean",
            "description": "Indicates if the provider is active."
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the provider was created."
          },
          "updatedAt": {
            "type": "string",
            "description": "The date when the provider was updated."
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.forumsdk.com/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": [],
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/auth/forgot-password": {
      "post": {
        "summary": "Forgot password",
        "description": "Endpoint for requesting a password reset.",
        "tags": [
          "Auth"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "description": "Email of the user",
                    "type": "string",
                    "required": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password reset token generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resetToken": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/login": {
      "post": {
        "summary": "User login",
        "description": "Endpoint for user login.",
        "tags": [
          "Auth"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "login": {
                    "type": "string",
                    "required": true
                  },
                  "password": {
                    "type": "string",
                    "required": true,
                    "format": "password"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful login",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/me": {
      "get": {
        "summary": "Get user information",
        "description": "Retrieve user information based on the provided JWT token.",
        "tags": [
          "Auth"
        ],
        "responses": {
          "200": {
            "description": "OK. User information retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. Invalid or missing JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "components": {
          "schemas": {
            "User": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "email": {
                  "type": "string"
                }
              }
            },
            "Error": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/register": {
      "post": {
        "summary": "User registration",
        "description": "Endpoint for user registration.",
        "tags": [
          "Auth"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": {
                    "description": "Username of the user (min 3 characters, max 30 characters, only letters, numbers, underscores, and hyphens)",
                    "type": "string"
                  },
                  "email": {
                    "description": "Email of the user",
                    "type": "string"
                  },
                  "displayName": {
                    "description": "Display name of the user",
                    "type": "string"
                  },
                  "password": {
                    "description": "Password of the user (min 8 characters)",
                    "type": "string",
                    "format": "password"
                  },
                  "emailVerified": {
                    "description": "Email verification status of the user",
                    "type": "boolean"
                  },
                  "roles": {
                    "description": "Roles of the user",
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "extendedData": {
                    "description": "Extended data of the user",
                    "type": "object"
                  }
                },
                "required": [
                  "username",
                  "email",
                  "password"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "$ref": "#/components/schemas/User"
                    },
                    "token": {
                      "type": "string",
                      "description": "JWT authentication token"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/reset-password": {
      "post": {
        "summary": "Reset password",
        "description": "Endpoint for resetting a user's password.",
        "tags": [
          "Auth"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "password": {
                    "description": "New password of the user (min 8 characters)",
                    "type": "string",
                    "required": true
                  },
                  "oldPassword": {
                    "description": "Old password of the user",
                    "type": "string"
                  },
                  "email": {
                    "description": "Email of the user",
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password reset successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/security": {
      "get": {
        "summary": "Get account security information",
        "description": "Retrieve security-related information for the authenticated user, including IP addresses and account activity.",
        "tags": [
          "Auth"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Security information retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "userId": {
                      "type": "string",
                      "description": "The user's ID"
                    },
                    "username": {
                      "type": "string",
                      "description": "The user's username"
                    },
                    "registrationIp": {
                      "type": "string",
                      "description": "IP address used during registration"
                    },
                    "registrationDate": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Account creation date"
                    },
                    "lastIp": {
                      "type": "string",
                      "description": "Most recent IP address used"
                    },
                    "lastSeenAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Last activity timestamp"
                    },
                    "isOnline": {
                      "type": "boolean",
                      "description": "Current online status"
                    },
                    "emailVerified": {
                      "type": "boolean",
                      "description": "Email verification status"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. Invalid or missing JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/integrations/{id}": {
      "get": {
        "summary": "Get integration",
        "description": "Get integration by ID",
        "tags": [
          "Integrations"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Integration not found"
          }
        }
      },
      "patch": {
        "summary": "Update integration",
        "description": "Update an integration's configuration",
        "tags": [
          "Integrations"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Integration ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Integration name"
                  },
                  "type": {
                    "type": "string",
                    "description": "Integration type"
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Whether the integration is enabled"
                  },
                  "config": {
                    "type": "object",
                    "description": "Integration configuration (will be encrypted)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Integration updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "integration": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "404": {
            "description": "Integration not found"
          }
        }
      },
      "delete": {
        "summary": "Delete integration",
        "description": "Delete an integration",
        "tags": [
          "Integrations"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Integration deleted"
          }
        }
      }
    },
    "/api/v1/integrations": {
      "get": {
        "summary": "List integrations",
        "description": "Get all integrations for the authenticated instance",
        "tags": [
          "Integrations"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "post": {
        "summary": "Create integration",
        "description": "Create a new integration (Slack, Discord, CRM, SSO)",
        "tags": [
          "Integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "type",
                  "name",
                  "config"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "SLACK",
                      "DISCORD",
                      "SALESFORCE",
                      "HUBSPOT",
                      "OKTA",
                      "AUTH0"
                    ]
                  },
                  "name": {
                    "type": "string"
                  },
                  "config": {
                    "type": "object",
                    "description": "Integration configuration (will be encrypted)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Integration created"
          },
          "403": {
            "description": "Feature not available in current tier"
          }
        }
      }
    },
    "/api/v1/integrations/oauth/{provider}/authorize": {
      "get": {
        "summary": "Initiate OAuth flow",
        "description": "Redirect to OAuth provider for authorization",
        "tags": [
          "Integrations"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "provider",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "hubspot",
                "salesforce"
              ]
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to OAuth provider"
          }
        }
      }
    },
    "/api/v1/integrations/oauth/{provider}/callback": {
      "get": {
        "summary": "OAuth callback",
        "description": "Handle OAuth callback from provider",
        "tags": [
          "Integrations"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "provider",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "code",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "state",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to app"
          }
        }
      }
    },
    "/api/v1/integrations/test": {
      "post": {
        "summary": "Test integration",
        "description": "Send a test message to verify integration is working",
        "tags": [
          "Integrations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "integrationId"
                ],
                "properties": {
                  "integrationId": {
                    "type": "string",
                    "description": "Integration ID to test"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Test message sent successfully"
          },
          "404": {
            "description": "Integration not found"
          },
          "500": {
            "description": "Test failed"
          }
        }
      }
    },
    "/api/v1/notification/{id}": {
      "get": {
        "summary": "Get a notification",
        "description": "Get a notification by its ID",
        "tags": [
          "Notification"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the notification"
          },
          {
            "in": "query",
            "name": "userId",
            "schema": {
              "type": "string"
            },
            "description": "User ID to verify ownership. For JWT authentication, automatically uses the authenticated user's ID (users can only access their own notifications). For API Key authentication, can be specified in the query."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Notification"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a notification",
        "description": "Update a notification property (e.g. read status)",
        "tags": [
          "Notification"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the notification"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User ID to verify ownership. For JWT authentication, automatically uses the authenticated user's ID. For API Key authentication, can be specified in the body."
                  },
                  "status": {
                    "type": "string",
                    "description": "Notification status. Common values include \"pending\", \"sent\", \"read\", \"dismissed\", \"archived\", \"failed\", \"draft\""
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Notification"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      },
      "delete": {
        "summary": "Delete a notification",
        "description": "Delete a notification by its ID",
        "tags": [
          "Notification"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the notification"
          },
          {
            "in": "query",
            "name": "userId",
            "schema": {
              "type": "string"
            },
            "description": "User ID to verify ownership. For JWT authentication, automatically uses the authenticated user's ID. For API Key authentication, can be specified in the query."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Notification"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean",
                          "description": "Indicates if the notification was deleted."
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/notification": {
      "post": {
        "summary": "Create a new notification",
        "description": "Create a new notification with the provided data",
        "tags": [
          "Notification"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "threadId": {
                    "type": "string"
                  },
                  "postId": {
                    "type": "string"
                  },
                  "privateMessageId": {
                    "type": "string"
                  },
                  "notifierId": {
                    "type": "string",
                    "description": "ID of the user creating the notification. Required only when using API Key authentication. When using JWT authentication, the notifier ID is automatically extracted from the token and cannot be overridden."
                  },
                  "notifiedId": {
                    "type": "string",
                    "description": "ID of the user receiving the notification. Required only when using API Key authentication. When using JWT authentication, the notifier ID is automatically extracted from the token and cannot be overridden."
                  },
                  "type": {
                    "type": "string",
                    "description": "Type of the notification. Common values include 'like', 'comment', 'reply', 'mention', 'follow', 'private-message', 'system', 'custom'."
                  },
                  "status": {
                    "type": "string",
                    "description": "Status of the notification. Common values include 'pending', 'sent', 'read', 'dismissed', 'archived', 'failed', 'draft'."
                  },
                  "extendedData": {
                    "type": "object",
                    "description": "Extended data for the notification. This can be any JSON object."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Notification"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/notifications": {
      "get": {
        "summary": "Get notifications",
        "description": "Retrieve a list of notifications.",
        "tags": [
          "Notifications"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "userId",
            "description": "The ID of the user. For JWT authentication, automatically uses the authenticated user's ID (users can only access their own notifications). For API Key authentication, can be specified in the query.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "description": "Filter notifications by status. Common values include \"pending\", \"sent\", \"read\", \"dismissed\", \"archived\", \"failed\", \"draft\"",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "filter",
            "description": "The filter to apply to the notifications.",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest"
              ]
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "The cursor for pagination.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of notifications to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Returns the list of notifications.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "list": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Notification"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. The user is not authorized to access the notifications.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed. The request method is not allowed for this endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Bulk update notifications",
        "description": "Update status (e.g. read/unread) for all notifications of a user.",
        "tags": [
          "Notifications"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "The user ID to update notifications for. For JWT authentication, automatically uses the authenticated user's ID (users can only update their own notifications). For API Key authentication, can be specified in the body."
                  },
                  "status": {
                    "type": "string",
                    "description": "The new status to set for all notifications. Common values include \"pending\", \"sent\", \"read\", \"dismissed\", \"archived\", \"failed\", \"draft\""
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer",
                      "description": "Number of records updated"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/v1/post/{id}/dislikes": {
      "get": {
        "summary": "Get post dislikes",
        "description": "Retrieve all dislikes for a post with cursor-based pagination.",
        "tags": [
          "Post"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Post ID"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (like ID)"
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of dislikes to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of dislikes retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dislikes": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Dislike a post",
        "description": "Add a dislike to a post.",
        "tags": [
          "Post"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User ID performing the dislike. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Disliked successfully."
          }
        }
      },
      "delete": {
        "summary": "Remove dislike from a post",
        "description": "Remove a dislike from a post.",
        "tags": [
          "Post"
        ],
        "responses": {
          "200": {
            "description": "Dislike removed successfully."
          }
        }
      }
    },
    "/api/v1/post/{id}/downvotes": {
      "get": {
        "summary": "Get post downvotes",
        "description": "Retrieve all downvotes for a post with cursor-based pagination.",
        "tags": [
          "Post"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Post ID"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (upvote ID)"
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of downvotes to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of downvotes retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "downvotes": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Downvote a post",
        "description": "Add a downvote to a post.",
        "tags": [
          "Post"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User ID performing the downvote. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Downvoted successfully."
          }
        }
      },
      "delete": {
        "summary": "Remove downvote from a post",
        "description": "Remove a downvote from a post.",
        "tags": [
          "Post"
        ],
        "responses": {
          "200": {
            "description": "Downvote removed successfully."
          }
        }
      }
    },
    "/api/v1/post/{id}/likes": {
      "get": {
        "summary": "Get post likes",
        "description": "Retrieve all likes for a post with cursor-based pagination.",
        "tags": [
          "Post"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Post ID"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (like ID)"
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of likes to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of likes retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "likes": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Like a post",
        "description": "Add a like to a post.",
        "tags": [
          "Post"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User ID performing the like. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Liked successfully."
          }
        }
      },
      "delete": {
        "summary": "Remove like from a post",
        "description": "Remove a like from a post.",
        "tags": [
          "Post"
        ],
        "responses": {
          "200": {
            "description": "Like removed successfully."
          }
        }
      }
    },
    "/api/v1/thread/{id}/posts": {
      "get": {
        "summary": "Get posts for a thread",
        "description": "Retrieve posts for a specific thread.",
        "tags": [
          "Thread"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the thread.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "query",
            "description": "The search query for posts.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "The cursor for pagination.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "filter",
            "description": "The filter option for sorting posts.",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest"
              ]
            }
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of posts to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Post"
                      }
                    },
                    "nextPostCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/post/{id}/upvotes": {
      "get": {
        "summary": "Get post upvotes",
        "description": "Retrieve all upvotes for a post with cursor-based pagination.",
        "tags": [
          "Post"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Post ID"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (upvote ID)"
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of upvotes to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of upvotes retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "upvotes": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Upvote a post",
        "description": "Add an upvote to a post.",
        "tags": [
          "Post"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User ID performing the upvote. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Upvoted successfully."
          }
        }
      },
      "delete": {
        "summary": "Remove upvote from a post",
        "description": "Remove an upvote from a post.",
        "tags": [
          "Post"
        ],
        "responses": {
          "200": {
            "description": "Upvote removed successfully."
          }
        }
      }
    },
    "/api/v1/post": {
      "post": {
        "summary": "Create a new post",
        "description": "Endpoint to create a new post.",
        "tags": [
          "Post"
        ],
        "requestBody": {
          "description": "Post data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "body",
                  "threadId"
                ],
                "properties": {
                  "body": {
                    "type": "string"
                  },
                  "threadId": {
                    "type": "string"
                  },
                  "userId": {
                    "type": "string",
                    "description": "User ID creating the post. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  },
                  "parentId": {
                    "type": "string"
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Post"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/posts": {
      "get": {
        "summary": "Get posts",
        "description": "Retrieve a list of posts, optionally filtered by interaction type (liked, etc).",
        "tags": [
          "Posts"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search query."
          },
          {
            "in": "query",
            "name": "filter",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest"
              ]
            },
            "description": "Sort order."
          },
          {
            "in": "query",
            "name": "type",
            "schema": {
              "type": "string",
              "enum": [
                "created",
                "liked",
                "disliked",
                "upvoted",
                "downvoted"
              ]
            },
            "description": "Filter posts by user interaction. Default is 'created' (posts authored by userId)."
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor."
          },
          {
            "in": "query",
            "name": "userId",
            "schema": {
              "type": "string"
            },
            "description": "The user ID to filter by (author or interactor)."
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of posts to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Returns the list of posts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Post"
                      }
                    },
                    "nextPostCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "405": {
            "description": "Method Not Allowed"
          }
        }
      }
    },
    "/api/v1/private-message/{id}": {
      "get": {
        "summary": "Get a private message by ID",
        "description": "Retrieve a private message by its ID",
        "tags": [
          "Private Message"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "ID of the private message.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "userId",
            "schema": {
              "type": "string"
            },
            "description": "User ID to verify access. For JWT authentication, automatically uses the authenticated user's ID (users can only access messages they sent or received). For API Key authentication, can be specified in the query."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrivateMessage"
                }
              }
            }
          },
          "404": {
            "description": "Private message not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Reply to a private message",
        "description": "Reply to a private message by its ID",
        "tags": [
          "Private Message"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "ID of the parent private message.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Request body for replying to a private message. The 'senderId' field from PrivateMessage is required only when using API Key authentication. When using JWT authentication, the sender ID is automatically extracted from the token and cannot be overridden. The 'title' field is not used for replies.",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/PrivateMessage"
                  },
                  {
                    "type": "object",
                    "required": [
                      "body",
                      "recipientId"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Private message created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PrivateMessage"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "The title of the private message.",
                          "default": null
                        },
                        "parentId": {
                          "type": "string",
                          "description": "The parent ID of the private message."
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing required fields or sender and recipient are the same",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a private message",
        "description": "Update the content of a private message. Only the sender can update their message.",
        "tags": [
          "Private Message"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "ID of the private message.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "Updated message content."
                  },
                  "extendedData": {
                    "type": "object",
                    "description": "Updated extended data."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Private message updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrivateMessage"
                }
              }
            }
          },
          "400": {
            "description": "Missing required fields"
          },
          "403": {
            "description": "Forbidden - Only sender can update"
          },
          "404": {
            "description": "Private message not found"
          }
        }
      },
      "delete": {
        "summary": "Delete a private message by ID",
        "description": "Delete a private message by its ID",
        "tags": [
          "Private Message"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "ID of the private message.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Private message deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PrivateMessage"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean",
                          "description": "Indicates if the private message was deleted."
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Private message not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/private-message": {
      "post": {
        "summary": "Create a private message",
        "description": "Endpoint to create a private message.",
        "tags": [
          "Private Message"
        ],
        "requestBody": {
          "description": "Private message object",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "body",
                  "recipientId"
                ],
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "body": {
                    "type": "string"
                  },
                  "recipientId": {
                    "type": "string"
                  },
                  "senderId": {
                    "type": "string",
                    "description": "Sender user ID. Required only when using API Key authentication. When using JWT authentication, the sender ID is automatically extracted from the token and cannot be overridden."
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrivateMessage"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/private-messages": {
      "get": {
        "summary": "Get private messages",
        "description": "Retrieve a list of private messages based on the provided filters.",
        "tags": [
          "Private Messages"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            },
            "description": "The search query string."
          },
          {
            "in": "query",
            "name": "userId",
            "schema": {
              "type": "string"
            },
            "description": "The user ID to filter private messages by. For JWT authentication, automatically uses the authenticated user's ID (users can only access their own messages). For API Key authentication, can be specified in the query."
          },
          {
            "in": "query",
            "name": "filter",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest"
              ]
            },
            "description": "The filter to sort the private messages by."
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "The cursor for pagination."
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of private messages to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Returns a list of private messages.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "privateMessages": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PrivateMessage"
                      }
                    },
                    "nextPrivateMessageCursor": {
                      "type": "string",
                      "description": "The cursor for the next page of private messages."
                    },
                    "count": {
                      "type": "integer",
                      "description": "The total count of private messages."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. The user is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "The error message."
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. Only GET method is supported.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "The error message."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/report/{id}": {
      "get": {
        "summary": "Get a report by ID",
        "description": "Retrieve a report by its ID.",
        "tags": [
          "Report"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the report.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Returns the requested report.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Report"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. User is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found. The requested report does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error. An error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Update a report",
        "description": "Update an existing report.",
        "tags": [
          "Report"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the report.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The updated report data.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "threadId": {
                    "type": "string"
                  },
                  "postId": {
                    "type": "string"
                  },
                  "privateMessageId": {
                    "type": "string"
                  },
                  "reportedId": {
                    "type": "string"
                  },
                  "reporterId": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "read": {
                    "type": "boolean"
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK. Returns the updated report.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Report"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request. Invalid request body.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found. The requested report does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error. An error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a report",
        "description": "Delete a report by its ID.",
        "tags": [
          "Report"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the report.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Returns the deleted report.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Report"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean",
                          "description": "Indicates if the report was deleted."
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error. An error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Partially update a report",
        "description": "Update specific fields of a report (e.g., read status).",
        "tags": [
          "Report"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the report.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The fields to update.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "read": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK. Returns the updated report.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Report"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized."
          },
          "404": {
            "description": "Not Found."
          }
        }
      }
    },
    "/api/v1/report": {
      "post": {
        "summary": "Create a report",
        "description": "Endpoint to create a report.",
        "tags": [
          "Report"
        ],
        "requestBody": {
          "description": "Report data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "threadId": {
                    "type": "string"
                  },
                  "postId": {
                    "type": "string"
                  },
                  "privateMessageId": {
                    "type": "string"
                  },
                  "reportedId": {
                    "type": "string"
                  },
                  "reporterId": {
                    "type": "string",
                    "description": "ID of the user filing the report. Required only when using API Key authentication. When using JWT authentication, the reporter ID is automatically extracted from the token and cannot be overridden."
                  },
                  "type": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Report created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Report"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Missing required fields.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/reports": {
      "get": {
        "summary": "Get reports",
        "description": "Retrieve a list of reports based on the provided filters.",
        "tags": [
          "Reports"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "reporterId",
            "description": "The ID of the reporting user. For JWT authentication, automatically uses the authenticated user's ID (users can only see reports they filed). For API Key authentication, can be specified in the query.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "reportedId",
            "description": "The ID of the reported user.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "description": "Filter reports by status. Common values include \"pending\", \"in_review\", \"resolved\", \"dismissed\", \"escalated\"",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "The cursor for pagination.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "filter",
            "description": "The filter to sort the reports.",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest"
              ]
            }
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of reports to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "list": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Report"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Bulk update reports",
        "description": "Update status (e.g. read/unread) for multiple reports.",
        "tags": [
          "Reports"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reportIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "status": {
                    "type": "string",
                    "description": "The new status to set for the reports. Common values include \"pending\", \"in_review\", \"resolved\", \"dismissed\", \"escalated\""
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/v1/role/{id}": {
      "get": {
        "summary": "Get role by ID",
        "description": "Retrieve a role by its ID",
        "tags": [
          "Role"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "ID of the role",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Role"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Update role by ID",
        "description": "Update a role by its ID",
        "tags": [
          "Role"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "ID of the role",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Role data to be updated",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "color": {
                    "type": "string"
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Role"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete role by ID",
        "description": "Delete a role by its ID",
        "tags": [
          "Role"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "ID of the role",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Role"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/role": {
      "post": {
        "summary": "Create a new role",
        "description": "Create a new role with the provided data",
        "tags": [
          "Role"
        ],
        "requestBody": {
          "description": "Role data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "color": {
                    "type": "string"
                  },
                  "extendedData": {
                    "type": "object"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Role created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Role"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/roles": {
      "get": {
        "summary": "Get roles",
        "description": "Retrieve a list of roles with optional filtering and pagination.",
        "tags": [
          "Roles"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "filter",
            "description": "The filter to apply to the roles list.",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest"
              ]
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "The cursor for pagination.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of roles to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Returns the list of roles.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "roles": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Role"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "description": "The cursor for the next page of results."
                    },
                    "count": {
                      "type": "integer",
                      "description": "The total count of roles."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. The user is not authorized to access the resource.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed. The requested HTTP method is not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error. An error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "summary": "Search for tags, posts, threads, or users.",
        "description": "This API endpoint allows you to search for tags, posts, threads, or users based on the provided query.",
        "tags": [
          "Search"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "required": true,
            "description": "The search query.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "type",
            "required": true,
            "description": "The type of search (threads, posts, users or tags).",
            "schema": {
              "type": "string",
              "enum": [
                "threads",
                "posts",
                "users",
                "tags"
              ]
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "The cursor for pagination.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of results to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "tags": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Tag"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "posts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Post"
                      }
                    },
                    "threads": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Thread"
                      }
                    },
                    "users": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sso/{id}": {
      "get": {
        "summary": "Get SSO provider",
        "description": "Retrieve details of a specific SSO provider configuration",
        "tags": [
          "SSO"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "SSO provider ID"
          }
        ],
        "responses": {
          "200": {
            "description": "SSO provider retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SSOProvider"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden - Requires ENTERPRISE tier"
          },
          "404": {
            "description": "SSO provider not found"
          }
        }
      },
      "patch": {
        "summary": "Update SSO provider",
        "description": "Update an SSO provider configuration",
        "tags": [
          "SSO"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "SSO provider ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Provider name"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "SAML",
                      "OIDC",
                      "OAUTH2"
                    ],
                    "description": "Provider type"
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Whether the provider is enabled"
                  },
                  "config": {
                    "type": "object",
                    "description": "Provider configuration object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SSO provider updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SSOProvider"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden - Requires ENTERPRISE tier"
          },
          "404": {
            "description": "SSO provider not found"
          }
        }
      },
      "delete": {
        "summary": "Delete SSO provider",
        "description": "Delete an SSO provider configuration",
        "tags": [
          "SSO"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SSO provider deleted"
          },
          "404": {
            "description": "SSO provider not found"
          }
        }
      }
    },
    "/api/v1/sso": {
      "get": {
        "summary": "List SSO providers",
        "description": "Get all SSO providers for the authenticated instance",
        "tags": [
          "SSO"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "post": {
        "summary": "Create SSO provider",
        "description": "Create a new SSO provider configuration",
        "tags": [
          "SSO"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "provider",
                  "domain",
                  "config"
                ],
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "OKTA",
                      "AUTH0",
                      "SAML"
                    ]
                  },
                  "domain": {
                    "type": "string",
                    "description": "Email domain (e.g., company.com)"
                  },
                  "config": {
                    "type": "object",
                    "description": "SSO configuration (will be encrypted)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SSO provider created"
          },
          "403": {
            "description": "SSO requires ENTERPRISE tier"
          }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "summary": "Get stats",
        "description": "Get stats for the current instance",
        "tags": [
          "Stats"
        ],
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "description": "Filter",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest"
              ],
              "default": "newest"
            }
          },
          {
            "name": "threadCursor",
            "in": "query",
            "description": "Thread cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "postCursor",
            "in": "query",
            "description": "Post cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userCursor",
            "in": "query",
            "description": "User cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "reportCursor",
            "in": "query",
            "description": "Report cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of items to return per page (min: 1, max: 50, default: 15)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stats",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "counts": {
                      "type": "object",
                      "properties": {
                        "threads": {
                          "type": "integer"
                        },
                        "posts": {
                          "type": "integer"
                        },
                        "users": {
                          "type": "integer"
                        },
                        "reports": {
                          "type": "integer"
                        }
                      }
                    },
                    "latest": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "type": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "usage": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "cursors": {
                      "type": "object",
                      "properties": {
                        "threadCursor": {
                          "type": "string"
                        },
                        "postCursor": {
                          "type": "string"
                        },
                        "userCursor": {
                          "type": "string"
                        },
                        "reportCursor": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tag/{id}": {
      "get": {
        "summary": "Get tag by ID",
        "description": "Retrieve a tag by its ID",
        "tags": [
          "Tag"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the tag"
          },
          {
            "in": "query",
            "name": "userId",
            "schema": {
              "type": "string"
            },
            "description": "ID of the user"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tag"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Update tag by ID",
        "description": "Update a tag by its ID",
        "tags": [
          "Tag"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the tag"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "color": {
                    "type": "string"
                  },
                  "extendedData": {
                    "type": "object"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tag"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete tag by ID",
        "description": "Delete a tag by its ID",
        "tags": [
          "Tag"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the tag"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tag"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tag/{id}/subscribers": {
      "get": {
        "summary": "Get tag subscribers",
        "description": "Retrieve all subscribers for a tag with cursor-based pagination.",
        "tags": [
          "Tag"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tag ID"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (user ID)"
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of subscribers to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of subscribers retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subscribers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized."
          },
          "404": {
            "description": "Tag not found."
          }
        }
      },
      "post": {
        "summary": "Subscribe user to a tag",
        "description": "Subscribe a user to a specific tag by providing the tag ID and user ID.",
        "tags": [
          "Tag"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the tag.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "The ID of the user subscribing. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tag subscription successful.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request."
          },
          "401": {
            "description": "Unauthorized."
          }
        }
      },
      "delete": {
        "summary": "Unsubscribe user from a tag",
        "description": "Unsubscribe a user from a specific tag.",
        "tags": [
          "Tag"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the tag.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "userId",
            "description": "The ID of the user unsubscribing. For JWT authentication, automatically uses the authenticated user's ID. For API Key authentication, can be specified in the query.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tag unsubscription successful."
          },
          "400": {
            "description": "Bad request."
          },
          "401": {
            "description": "Unauthorized."
          }
        }
      }
    },
    "/api/v1/tag/{id}/threads": {
      "get": {
        "summary": "Get threads with a specific tag",
        "description": "Retrieve a list of threads associated with a specific tag with cursor-based pagination.",
        "tags": [
          "Tag"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the tag."
          },
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search query to filter threads by title."
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (thread ID)."
          },
          {
            "in": "query",
            "name": "filter",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest",
                "recent"
              ]
            },
            "description": "Sort order for threads."
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of threads to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of threads retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "threads": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Thread"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Tag not found"
          }
        }
      }
    },
    "/api/v1/tag": {
      "post": {
        "summary": "Create a new tag",
        "description": "Endpoint to create a new tag.",
        "tags": [
          "Tag"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "color": {
                    "type": "string"
                  },
                  "extendedData": {
                    "type": "object"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tag created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tag"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tags": {
      "get": {
        "summary": "Get tags with threads",
        "description": "Retrieve a list of tags with associated threads.",
        "tags": [
          "Tags"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "description": "Search query for tags by name or description (supports partial and case-insensitive matching).",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "Cursor for pagination.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of tags to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          },
          {
            "in": "query",
            "name": "includeThreads",
            "description": "Whether to include thread data in the response (default: true).",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tags": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Tag"
                      }
                    },
                    "nextTagCursor": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tags/subscribed": {
      "get": {
        "summary": "Get subscribed tags with threads",
        "description": "Retrieve a list of subscribed tags with associated threads.",
        "tags": [
          "Tags"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "userId",
            "description": "User ID to get subscribed tags for. For JWT authentication, automatically uses the authenticated user's ID (users can only see tags they subscribed to). For API Key authentication, can be specified in the query.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "query",
            "description": "Search query for subscribed tags by name or description.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "Cursor for pagination.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of tags to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tags": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Tag"
                      }
                    },
                    "nextTagCursor": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/thread/{id}/dislikes": {
      "get": {
        "summary": "Get thread dislikes",
        "description": "Retrieve all dislikes for a thread with cursor-based pagination.",
        "tags": [
          "Thread"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Thread ID"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (like ID)"
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of dislikes to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of dislikes retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dislikes": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Dislike a thread",
        "description": "Add a dislike to a thread.",
        "tags": [
          "Thread"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User ID performing the dislike. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Disliked successfully."
          }
        }
      },
      "delete": {
        "summary": "Remove dislike from a thread",
        "description": "Remove a dislike from a thread.",
        "tags": [
          "Thread"
        ],
        "responses": {
          "200": {
            "description": "Dislike removed successfully."
          }
        }
      }
    },
    "/api/v1/thread/{id}/downvotes": {
      "get": {
        "summary": "Get thread downvotes",
        "description": "Retrieve all downvotes for a thread with cursor-based pagination.",
        "tags": [
          "Thread"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Thread ID"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (upvote ID)"
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of downvotes to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of downvotes retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "downvotes": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Downvote a thread",
        "description": "Add a downvote to a thread.",
        "tags": [
          "Thread"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User ID performing the downvote. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Downvoted successfully."
          }
        }
      },
      "delete": {
        "summary": "Remove downvote from a thread",
        "description": "Remove a downvote from a thread.",
        "tags": [
          "Thread"
        ],
        "responses": {
          "200": {
            "description": "Downvote removed successfully."
          }
        }
      }
    },
    "/api/v1/thread/{id}": {
      "get": {
        "summary": "Get a thread by ID",
        "description": "Retrieve a thread by its ID",
        "tags": [
          "Thread"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the thread"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Thread"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Thread not found"
          },
          "500": {
            "description": "Internal Server Error"
          }
        }
      },
      "put": {
        "summary": "Update a thread",
        "description": "Update a thread by its ID",
        "tags": [
          "Thread"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the thread"
          }
        ],
        "requestBody": {
          "description": "Thread data to be updated",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  },
                  "body": {
                    "type": "string"
                  },
                  "userId": {
                    "type": "string",
                    "description": "User ID updating the thread. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden. User must have permission to modify the thread."
                  },
                  "locked": {
                    "type": "boolean"
                  },
                  "pinned": {
                    "type": "boolean"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Array of tag IDs to associate with the thread"
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Thread"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Thread not found"
          },
          "500": {
            "description": "Internal Server Error"
          }
        }
      },
      "delete": {
        "summary": "Delete a thread",
        "description": "Delete a thread by its ID",
        "tags": [
          "Thread"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the thread"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Thread"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/thread/{id}/likes": {
      "get": {
        "summary": "Get thread likes",
        "description": "Retrieve all likes for a thread with cursor-based pagination.",
        "tags": [
          "Thread"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Thread ID"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (like ID)"
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of likes to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of likes retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "likes": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Like a thread",
        "description": "Add a like to a thread.",
        "tags": [
          "Thread"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User ID performing the like. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Liked successfully."
          }
        }
      },
      "delete": {
        "summary": "Remove like from a thread",
        "description": "Remove a like from a thread.",
        "tags": [
          "Thread"
        ],
        "responses": {
          "200": {
            "description": "Like removed successfully."
          }
        }
      }
    },
    "/api/v1/thread/{id}/poll": {
      "post": {
        "summary": "Create a poll for a thread",
        "description": "Create a poll for a thread with the specified ID",
        "tags": [
          "Thread - Poll"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the thread",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Poll details",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "The title of the poll"
                  },
                  "expiresAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "The expiration date and time of the poll"
                  },
                  "options": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "The title of the poll option"
                        },
                        "color": {
                          "type": "string",
                          "description": "The color of the poll option"
                        },
                        "extendedData": {
                          "type": "object",
                          "description": "Additional data for the poll option"
                        }
                      }
                    }
                  },
                  "extendedData": {
                    "type": "object",
                    "description": "Additional data for the poll"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Poll created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Poll"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "closed": {
                          "type": "boolean",
                          "description": "Indicates if the poll was closed",
                          "default": false
                        },
                        "closedAt": {
                          "type": "string",
                          "format": "date-time",
                          "description": "The closed date and time of the poll",
                          "default": null
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Missing required fields or invalid data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. User is not subscribed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Thread not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Get the poll for a thread",
        "description": "Get the poll for a thread with the specified ID",
        "tags": [
          "Thread - Poll"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the thread",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Poll retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Poll"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. User is not subscribed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Poll not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Update the poll for a thread",
        "description": "Update the poll for a thread with the specified ID",
        "tags": [
          "Thread - Poll"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the thread",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Poll details",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "The updated title of the poll"
                  },
                  "expiresAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "The updated expiration date and time of the poll"
                  },
                  "closed": {
                    "type": "boolean",
                    "description": "Indicates if the poll is closed"
                  },
                  "options": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The ID of the poll option"
                        },
                        "title": {
                          "type": "string",
                          "description": "The updated title of the poll option"
                        },
                        "color": {
                          "type": "string",
                          "description": "The updated color of the poll option"
                        },
                        "extendedData": {
                          "type": "object",
                          "description": "The updated additional data for the poll option"
                        }
                      }
                    }
                  },
                  "extendedData": {
                    "type": "object",
                    "description": "The updated additional data for the poll"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Poll updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Poll"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Missing required fields or invalid data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. User is not subscribed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Poll not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete the poll for a thread",
        "description": "Delete the poll for a thread with the specified ID",
        "tags": [
          "Thread - Poll"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the thread",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Poll deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Poll"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean",
                          "description": "Indicates if the poll was deleted."
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. User is not subscribed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Poll not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/thread/{id}/poll/results": {
      "get": {
        "summary": "Get poll results",
        "description": "Endpoint to get poll results associated with a thread (returns vote counts, not individual votes)",
        "tags": [
          "Thread",
          "Poll"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "The ID of the thread",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "userId",
            "description": "Optional user ID to check which option they voted for. For JWT authentication, automatically uses the authenticated user's ID (private voting - users can only see their own vote). For API Key authentication, can be specified in the query.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with the poll results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PollResults"
                }
              }
            }
          },
          "400": {
            "description": "Thread does not have a poll",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/thread/{id}/poll/votes": {
      "post": {
        "summary": "Cast a new vote",
        "description": "Create a vote for a poll option in a thread",
        "tags": [
          "Thread",
          "Poll"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "optionId"
                ],
                "properties": {
                  "optionId": {
                    "type": "string",
                    "description": "The ID of the poll option to vote for"
                  },
                  "userId": {
                    "type": "string",
                    "description": "User ID casting the vote. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Vote created successfully"
          },
          "400": {
            "description": "Invalid input or user already voted"
          },
          "401": {
            "description": "Unauthorized"
          },
          "405": {
            "description": "Method not allowed"
          }
        }
      },
      "put": {
        "summary": "Change or upsert a vote",
        "description": "Update a user's vote or create it if none exists",
        "tags": [
          "Thread",
          "Poll",
          "Votes"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "optionId"
                ],
                "properties": {
                  "optionId": {
                    "type": "string",
                    "description": "The ID of the poll option to vote for"
                  },
                  "userId": {
                    "type": "string",
                    "description": "User ID changing the vote. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Vote updated successfully"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Unauthorized"
          },
          "405": {
            "description": "Method not allowed"
          }
        }
      },
      "delete": {
        "summary": "Remove a vote",
        "description": "Deletes a user's vote for a poll",
        "tags": [
          "Thread",
          "Poll",
          "Votes"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Vote deleted successfully"
          },
          "400": {
            "description": "Invalid thread or poll"
          },
          "401": {
            "description": "Unauthorized"
          },
          "405": {
            "description": "Method not allowed"
          }
        }
      }
    },
    "/api/v1/thread/{id}/subscribers": {
      "get": {
        "summary": "Get thread subscribers",
        "description": "Retrieve all subscribers for a thread with cursor-based pagination.",
        "tags": [
          "Thread"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Thread ID"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (subscription ID)"
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of subscribers to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of subscribers retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subscribers": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Subscribe to a thread",
        "description": "Subscribe a user to a thread.",
        "tags": [
          "Thread"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User ID subscribing to the thread. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscribed successfully."
          },
          "409": {
            "description": "Already subscribed."
          }
        }
      },
      "delete": {
        "summary": "Unsubscribe from a thread",
        "description": "Unsubscribe a user from a thread.",
        "tags": [
          "Thread"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "userId",
            "schema": {
              "type": "string"
            },
            "description": "User ID to unsubscribe. For JWT authentication, automatically uses the authenticated user's ID. For API Key authentication, can be specified in query or body."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unsubscribed successfully."
          }
        }
      }
    },
    "/api/v1/thread/{id}/upvotes": {
      "get": {
        "summary": "Get thread upvotes",
        "description": "Retrieve all upvotes for a thread with cursor-based pagination.",
        "tags": [
          "Thread"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Thread ID"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (upvote ID)"
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of upvotes to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of upvotes retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "upvotes": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Upvote a thread",
        "description": "Add an upvote to a thread.",
        "tags": [
          "Thread"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User ID performing the upvote. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Upvoted successfully."
          }
        }
      },
      "delete": {
        "summary": "Remove upvote from a thread",
        "description": "Remove an upvote from a thread.",
        "tags": [
          "Thread"
        ],
        "responses": {
          "200": {
            "description": "Upvote removed successfully."
          }
        }
      }
    },
    "/api/v1/thread": {
      "post": {
        "summary": "Create a new thread",
        "description": "Endpoint to create a new thread.",
        "tags": [
          "Thread"
        ],
        "requestBody": {
          "description": "Thread data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "required": true
                  },
                  "slug": {
                    "type": "string"
                  },
                  "body": {
                    "type": "string",
                    "required": true
                  },
                  "userId": {
                    "type": "string",
                    "description": "User ID creating the thread. Required only when using API Key authentication. When using JWT authentication, the user ID is automatically extracted from the token and cannot be overridden."
                  },
                  "locked": {
                    "type": "boolean"
                  },
                  "pinned": {
                    "type": "boolean"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "poll": {
                    "type": "object",
                    "properties": {
                      "title": {
                        "type": "string"
                      },
                      "options": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "color": {
                              "type": "string"
                            },
                            "title": {
                              "type": "string"
                            },
                            "extendedData": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    }
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Thread"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/threads": {
      "get": {
        "summary": "Get threads",
        "description": "Retrieve a list of threads based on the provided filters and interaction type.",
        "tags": [
          "Threads"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "description": "The search query string.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "tagId",
            "description": "The ID of the tag.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "filter",
            "description": "The filter to sort the threads.",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest",
                "recent"
              ]
            }
          },
          {
            "in": "query",
            "name": "type",
            "description": "Filter threads by user interaction (created, liked, subscribed, etc).",
            "schema": {
              "type": "string",
              "enum": [
                "created",
                "liked",
                "disliked",
                "upvoted",
                "downvoted",
                "subscribed"
              ]
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "The cursor for the next page of threads.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "userId",
            "description": "The user ID to filter by.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of threads to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Returns the list of threads.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "threads": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Thread"
                      }
                    },
                    "nextThreadCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized."
          },
          "405": {
            "description": "Method Not Allowed."
          }
        }
      }
    },
    "/api/v1/user/{id}/followers": {
      "get": {
        "summary": "Get followers of a user",
        "description": "Retrieve the followers of a user by their ID.",
        "tags": [
          "User"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the user."
          },
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search query"
          },
          {
            "in": "query",
            "name": "filter",
            "schema": {
              "type": "string"
            },
            "description": "The filter to sort the results."
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "The cursor for pagination."
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of followers to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "post": {
        "summary": "Add a follower (Follow user)",
        "description": "Make a user (followerId) follow the target user (id).",
        "tags": [
          "User"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "followerId": {
                    "type": "string",
                    "description": "ID of the user who is following. Required only when using API Key authentication. When using JWT authentication, the follower ID is automatically extracted from the token and cannot be overridden."
                  },
                  "extendedData": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Follow successful"
          }
        }
      },
      "delete": {
        "summary": "Remove a follower (Unfollow user)",
        "description": "Make a user (followerId) unfollow the target user (id).",
        "tags": [
          "User"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "followerId",
            "schema": {
              "type": "string"
            },
            "description": "ID of the user who is unfollowing. For JWT authentication, automatically uses the authenticated user's ID. For API Key authentication, can be specified in query or body."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "followerId": {
                    "type": "string",
                    "description": "ID of the user who is unfollowing. Required only when using API Key authentication. When using JWT authentication, the follower ID is automatically extracted from the token and cannot be overridden."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unfollow successful"
          }
        }
      }
    },
    "/api/v1/user/{id}/following": {
      "get": {
        "summary": "Get users that a user is following",
        "description": "Retrieve a list of users that a user is following.",
        "tags": [
          "User"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the user."
          },
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            },
            "description": "The search query to filter users by username or display name."
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "The cursor for pagination."
          },
          {
            "in": "query",
            "name": "filter",
            "schema": {
              "type": "string"
            },
            "description": "The filter to sort the results."
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of users to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response. Returns a list of users.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "following": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Follow"
                      }
                    },
                    "nextUserCursor": {
                      "type": "string",
                      "description": "The cursor for the next page of results."
                    },
                    "count": {
                      "type": "integer",
                      "description": "The total count of users."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. The user is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "The error message."
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. Only GET method is supported.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "The error message."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/user/{id}": {
      "get": {
        "summary": "Get user by ID",
        "description": "Retrieve user information by ID",
        "tags": [
          "User"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "ID of the user",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Update user by ID",
        "description": "Update user information by ID",
        "tags": [
          "User"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "ID of the user",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "User data to be updated",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": {
                    "description": "Username of the user (min 3 characters, max 30 characters, only letters, numbers, underscores, and hyphens)",
                    "type": "string"
                  },
                  "email": {
                    "description": "Email of the user",
                    "type": "string"
                  },
                  "displayName": {
                    "description": "Display name of the user",
                    "type": "string"
                  },
                  "password": {
                    "description": "Password of the user (min 8 characters)",
                    "type": "string",
                    "format": "password"
                  },
                  "emailVerified": {
                    "description": "Email verification status of the user",
                    "type": "boolean"
                  },
                  "roles": {
                    "description": "Roles of the user",
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "bio": {
                    "description": "Bio of the user",
                    "type": "string"
                  },
                  "signature": {
                    "description": "Signature of the user",
                    "type": "string"
                  },
                  "url": {
                    "description": "URL of the user",
                    "type": "string"
                  },
                  "extendedData": {
                    "description": "Extended data of the user",
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete user by ID",
        "description": "Delete user by ID",
        "tags": [
          "User"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "description": "ID of the user",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/user/{id}/posts": {
      "get": {
        "summary": "Get posts created by a user",
        "description": "Retrieve a list of posts created by a specific user with cursor-based pagination.",
        "tags": [
          "User"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the user."
          },
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search query to filter posts by body content."
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (post ID)."
          },
          {
            "in": "query",
            "name": "filter",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest"
              ]
            },
            "description": "Sort order for posts."
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of posts to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of posts retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Post"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "User not found"
          }
        }
      }
    },
    "/api/v1/user/{id}/threads": {
      "get": {
        "summary": "Get threads created by a user",
        "description": "Retrieve a list of threads created by a specific user with cursor-based pagination.",
        "tags": [
          "User"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the user."
          },
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search query to filter threads by title."
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor (thread ID)."
          },
          {
            "in": "query",
            "name": "filter",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest",
                "recent"
              ]
            },
            "description": "Sort order for threads."
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of threads to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of threads retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "threads": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Thread"
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "User not found"
          }
        }
      }
    },
    "/api/v1/user": {
      "post": {
        "summary": "Create a new user",
        "description": "Endpoint to create a new user.",
        "tags": [
          "User"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": {
                    "type": "string",
                    "description": "Username of the user (min 3 characters, max 30 characters, only letters, numbers, underscores, and hyphens)"
                  },
                  "email": {
                    "type": "string",
                    "description": "Email of the user"
                  },
                  "displayName": {
                    "type": "string",
                    "description": "Display name of the user"
                  },
                  "password": {
                    "type": "string",
                    "format": "password",
                    "description": "Password of the user (min 8 characters)"
                  },
                  "emailVerified": {
                    "type": "boolean",
                    "description": "Email verification status of the user"
                  },
                  "roles": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Roles of the user"
                  },
                  "bio": {
                    "type": "string",
                    "description": "Bio of the user"
                  },
                  "signature": {
                    "type": "string",
                    "description": "Signature of the user"
                  },
                  "url": {
                    "type": "string",
                    "description": "URL of the user"
                  },
                  "extendedData": {
                    "type": "object",
                    "description": "Extended data of the user"
                  }
                },
                "required": [
                  "username",
                  "email",
                  "password"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/users": {
      "get": {
        "summary": "Get a list of users",
        "description": "Retrieve a paginated list of users based on the provided query parameters.",
        "tags": [
          "Users"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            },
            "description": "The search query to filter users by username or display name."
          },
          {
            "in": "query",
            "name": "filter",
            "schema": {
              "type": "string"
            },
            "description": "The filter to sort the results by."
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "The cursor for the next page of results."
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of users to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with a list of users.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    },
                    "nextUserCursor": {
                      "type": "string",
                      "description": "The cursor for the next page of results."
                    },
                    "count": {
                      "type": "integer",
                      "description": "The total count of users."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "The error message."
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "The error message."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/{id}/deliveries": {
      "get": {
        "summary": "Get webhook deliveries",
        "description": "Get delivery history for a webhook",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Webhook ID"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Cursor for pagination"
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Number of deliveries to return per page (min: 1, max: 50, default: 15)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deliveries": {
                      "type": "array"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "nextCursor": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Webhook not found"
          }
        }
      }
    },
    "/api/v1/webhooks/{id}": {
      "get": {
        "summary": "Get webhook",
        "description": "Get a webhook by ID",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Webhook ID"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Webhook not found"
          }
        }
      },
      "patch": {
        "summary": "Update webhook",
        "description": "Update webhook configuration",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "active": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook updated"
          },
          "404": {
            "description": "Webhook not found"
          }
        }
      },
      "delete": {
        "summary": "Delete webhook",
        "description": "Delete a webhook",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook deleted"
          },
          "404": {
            "description": "Webhook not found"
          }
        }
      }
    },
    "/api/v1/webhooks": {
      "get": {
        "summary": "List webhooks",
        "description": "Get all webhooks for the authenticated instance",
        "tags": [
          "Webhooks"
        ],
        "responses": {
          "200": {
            "description": "OK. Returns the list of webhooks.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "webhooks": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      },
      "post": {
        "summary": "Create webhook",
        "description": "Create a new webhook subscription",
        "tags": [
          "Webhooks"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "url",
                  "events"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Webhook name"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Webhook URL"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Array of event types to subscribe to"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created successfully"
          },
          "400": {
            "description": "Bad request"
          },
          "403": {
            "description": "Webhook limit exceeded"
          }
        }
      }
    }
  },
  "tags": []
}