{
  "openapi": "3.0.1",
  "info": {
    "title": "ZAST.AI Business API",
    "version": "v1.0.0",
    "description": "# ZAST.AI Business API Documentation\n\nWelcome to the ZAST.AI Business API documentation. This API handles business logic, subscriptions, authentication, and notifications.\n\n## Features\n\n- **Subscription Management**: Manage Stripe subscriptions, portal sessions, and checkout sessions.\n- **Authentication**: Clerk authentication integration.\n- **Notifications**: Manage user notifications.\n- **Credit Management**: Check credit usage and limits."
  },
  "servers": [
    {
      "url": "https://zast.ai",
      "description": "Generated server url"
    }
  ],
  "paths": {
    "/biz/api/v1/subscribe/stripe/create-portal-session": {
      "post": {
        "tags": [
          "stripe-subscribe-controller"
        ],
        "summary": "Create Portal Session",
        "description": "Creates a Stripe portal session for managing subscriptions. This allows users to view and manage their subscription status and billing information.",
        "operationId": "createPortalSession",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePortalSessionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/CreatePortalSessionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/biz/api/v1/subscribe/stripe/create-checkout-session": {
      "post": {
        "tags": [
          "stripe-subscribe-controller"
        ],
        "summary": "Create Checkout Session",
        "description": "Creates a Stripe checkout session for processing payments. This initiates the subscription payment flow.",
        "operationId": "createCheckoutSession",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCheckoutSessionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/CreateCheckoutSessionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/biz/api/v1/notifications/update": {
      "post": {
        "tags": [
          "notification-controller"
        ],
        "summary": "Update Notifications",
        "description": "Updates the status of notifications, such as marking them as read or flagged.",
        "operationId": "updateNotification",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateNotificationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/biz/api/v1/notifications/search": {
      "post": {
        "tags": [
          "notification-controller"
        ],
        "summary": "Search Notifications",
        "description": "Retrieves a list of notifications based on search criteria, supporting pagination and filtering.",
        "operationId": "listNotifications",
        "parameters": [
          {
            "name": "X-User-Language",
            "in": "header",
            "required": false,
            "description": "Language for the response content (e.g., 'en', 'zh').",
            "schema": {
              "type": "string",
              "default": "en"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListNotificationsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ListNotificationsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/biz/api/v1/notifications/delete": {
      "post": {
        "tags": [
          "notification-controller"
        ],
        "summary": "Delete Notifications",
        "description": "Deletes specified notifications by their IDs.",
        "operationId": "deleteNotifications",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteNotificationsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/biz/api/v1/subscribe/stripe/exceed-credit-limit": {
      "get": {
        "tags": [
          "stripe-subscribe-controller"
        ],
        "summary": "Check Credit Limit",
        "description": "Checks if the user has exceeded their credit limit for the current subscription period.",
        "operationId": "getExceedCreditLimit",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/GetExceedCreditLimitResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/biz/api/v1/subscribe/stripe/active-subscription-category": {
      "get": {
        "tags": [
          "stripe-subscribe-controller"
        ],
        "summary": "Get Active Subscription Category",
        "description": "Retrieves the category of the active subscription for the user.",
        "operationId": "getActiveStripSubscriptionCategory",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/GetActiveStripSubscriptionCategoryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/biz/api/v1/auth/clerk/publishable-key": {
      "get": {
        "tags": [
          "authentication-clerk-controller"
        ],
        "summary": "Get Clerk Publishable Key",
        "description": "Retrieves the Clerk publishable key required for initializing the Clerk frontend SDK and performing user authentication.",
        "operationId": "getClerkPublishableKey",
        "responses": {
          "400": {
            "description": "Bad Request",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/GetClerkPublishableKeyResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "description": "Standard error response structure.",
        "properties": {
          "errCode": {
            "type": "integer",
            "format": "int32",
            "description": "Error code identifying the type of error."
          },
          "errMsg": {
            "type": "string",
            "description": "Brief error message."
          },
          "detail": {
            "type": "string",
            "description": "Detailed description of the error."
          }
        }
      },
      "CreatePortalSessionRequest": {
        "type": "object",
        "description": "Request body for creating a portal session.",
        "properties": {
          "returnUrl": {
            "type": "string",
            "description": "The URL to redirect to after the portal session is closed."
          }
        }
      },
      "CreatePortalSessionResponse": {
        "type": "object",
        "description": "Response body containing the portal session URL.",
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL for the created portal session."
          }
        }
      },
      "CreateCheckoutSessionRequest": {
        "type": "object",
        "description": "Request body for creating a checkout session.",
        "properties": {
          "category": {
            "type": "string",
            "description": "The subscription category or plan ID."
          },
          "successUrl": {
            "type": "string",
            "description": "The URL to redirect to upon successful payment."
          },
          "cancelUrl": {
            "type": "string",
            "description": "The URL to redirect to if payment is cancelled."
          }
        }
      },
      "CreateCheckoutSessionResponse": {
        "type": "object",
        "description": "Response body containing the checkout session URL.",
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL for the created checkout session."
          }
        }
      },
      "Filter": {
        "type": "object",
        "description": "Filter criteria for search operations.",
        "properties": {
          "field": {
            "type": "string",
            "description": "The field to filter by."
          },
          "op": {
            "type": "string",
            "description": "The comparison operator.",
            "enum": [
              "eq",
              "ne",
              "gt",
              "ge",
              "lt",
              "le",
              "like",
              "in",
              "between",
              "unsupported"
            ]
          },
          "value": {
            "type": "object",
            "description": "The value to compare against."
          }
        }
      },
      "UpdateNotificationRequest": {
        "required": [
          "notificationIds"
        ],
        "type": "object",
        "description": "Request body for updating notification status.",
        "properties": {
          "notificationIds": {
            "type": "array",
            "description": "List of notification IDs to update.",
            "items": {
              "type": "string"
            }
          },
          "read": {
            "type": "boolean",
            "description": "Set to true to mark notifications as read."
          },
          "mark": {
            "type": "boolean",
            "description": "Set to true to flag or mark notifications."
          }
        }
      },
      "ListNotificationsRequest": {
        "required": [
          "page",
          "size"
        ],
        "type": "object",
        "description": "Request body for listing notifications.",
        "properties": {
          "page": {
            "minimum": 0,
            "type": "integer",
            "format": "int32",
            "description": "Page number for pagination (0-indexed)."
          },
          "size": {
            "minimum": 1,
            "type": "integer",
            "format": "int32",
            "description": "Number of items per page."
          },
          "filters": {
            "type": "array",
            "description": "List of filters to apply.",
            "items": {
              "$ref": "#/components/schemas/Filter"
            }
          },
          "sorts": {
            "type": "array",
            "description": "List of sorting criteria (e.g., 'createdAt,desc').",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ListNotificationsResponse": {
        "type": "object",
        "description": "Response body containing a list of notifications.",
        "properties": {
          "data": {
            "type": "array",
            "description": "Array of notification objects.",
            "items": {
              "$ref": "#/components/schemas/NotificationInfo"
            }
          },
          "total": {
            "type": "integer",
            "format": "int32",
            "description": "Total number of notifications matching the criteria."
          }
        }
      },
      "NotificationInfo": {
        "type": "object",
        "description": "Detailed information about a notification.",
        "properties": {
          "notificationId": {
            "type": "string",
            "description": "Unique identifier for the notification."
          },
          "title": {
            "type": "string",
            "description": "Title or subject of the notification."
          },
          "content": {
            "type": "string",
            "description": "Body content of the notification."
          },
          "senderId": {
            "type": "string",
            "description": "ID of the sender."
          },
          "senderName": {
            "type": "string",
            "description": "Name of the sender."
          },
          "read": {
            "type": "boolean",
            "description": "Indicates if the notification has been read."
          },
          "mark": {
            "type": "boolean",
            "description": "Indicates if the notification has been marked/flagged."
          },
          "receivedAt": {
            "type": "string",
            "description": "Timestamp when the notification was received."
          },
          "meta": {
            "type": "object",
            "description": "Additional metadata associated with the notification.",
            "additionalProperties": {
              "type": "object"
            }
          }
        }
      },
      "DeleteNotificationsRequest": {
        "required": [
          "notificationIds"
        ],
        "type": "object",
        "description": "Request body for deleting notifications.",
        "properties": {
          "notificationIds": {
            "type": "array",
            "description": "List of notification IDs to delete.",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "GetExceedCreditLimitResponse": {
        "type": "object",
        "description": "Response indicating credit limit status.",
        "properties": {
          "activeSubscriptionId": {
            "type": "string",
            "description": "ID of the current active subscription."
          },
          "exceedCreditLimit": {
            "type": "boolean",
            "description": "True if the credit limit has been exceeded."
          },
          "creditsUsage": {
            "type": "integer",
            "format": "int64",
            "description": "Amount of credits used in the current period."
          },
          "firstTierLimit": {
            "type": "integer",
            "format": "int64",
            "description": "Limit of the first tier."
          },
          "customerCreditsLimit": {
            "type": "integer",
            "format": "int64",
            "description": "Total credit limit for the customer."
          },
          "periodStart": {
            "type": "integer",
            "format": "int64",
            "description": "Timestamp for the start of the current period."
          },
          "periodEnd": {
            "type": "integer",
            "format": "int64",
            "description": "Timestamp for the end of the current period."
          },
          "periodStartAt": {
            "type": "string",
            "description": "Formatted string of the start time."
          },
          "periodEndAt": {
            "type": "string",
            "description": "Formatted string of the end time."
          }
        }
      },
      "GetActiveStripSubscriptionCategoryResponse": {
        "type": "object",
        "description": "Response containing the active subscription category.",
        "properties": {
          "category": {
            "type": "string",
            "description": "The category name of the active subscription."
          }
        }
      },
      "GetClerkPublishableKeyResponse": {
        "type": "object",
        "properties": {
          "publishableKey": {
            "type": "string"
          }
        }
      }
    }
  }
}