{ "version": "1.0", "modules": [ { "name": "Stock Management", "prefix": "/stock-management", "endpoints": [ { "method": "POST", "path": "/sectors", "summary": "Create Sector", "description": "Creates a new sector record. Validates that the sector name is unique. Returns 409 if a sector with the same name already exists.", "request_body": { "schema_name": "SectorCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false } ] }, "response": { "schema_name": "SectorResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/sectors", "summary": "List Sectors", "description": "Returns a paginated list of sectors ordered by display_order and name. Supports optional search filter on sector name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "SectorResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/sectors/{sector_id}", "summary": "Get Sector", "description": "Retrieves a single sector by ID. Returns 404 if the sector does not exist.", "path_params": [ { "name": "sector_id", "type": "str" } ], "response": { "schema_name": "SectorResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/sectors/{sector_id}", "summary": "Update Sector", "description": "Updates an existing sector. Validates that the new name is unique if changed. Returns 404 if sector not found, 409 if name conflict.", "path_params": [ { "name": "sector_id", "type": "str" } ], "request_body": { "schema_name": "SectorUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "SectorResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/sectors/{sector_id}", "summary": "Delete Sector", "description": "Deletes a sector. Returns 404 if sector not found, 409 if sector is referenced by existing stocks.", "path_params": [ { "name": "sector_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/exchanges", "summary": "Create Exchange", "description": "Creates a new exchange record. Validates that the exchange code is unique. Returns 409 if an exchange with the same code already exists.", "request_body": { "schema_name": "ExchangeCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "code", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "timezone", "type": "str", "required": false }, { "name": "trading_hours", "type": "str", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "ExchangeResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "code", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "timezone", "type": "str", "required": false }, { "name": "trading_hours", "type": "str", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/exchanges", "summary": "List Exchanges", "description": "Returns a paginated list of exchanges ordered by name. Supports optional search filter on name or code, and country filter.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false } ], "response": { "schema_name": "ExchangeResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "code", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "timezone", "type": "str", "required": false }, { "name": "trading_hours", "type": "str", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/exchanges/{exchange_id}", "summary": "Get Exchange", "description": "Retrieves a single exchange by ID. Returns 404 if the exchange does not exist.", "path_params": [ { "name": "exchange_id", "type": "str" } ], "response": { "schema_name": "ExchangeResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "code", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "timezone", "type": "str", "required": false }, { "name": "trading_hours", "type": "str", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/exchanges/{exchange_id}", "summary": "Update Exchange", "description": "Updates an existing exchange. Validates that the new code is unique if changed. Returns 404 if exchange not found, 409 if code conflict.", "path_params": [ { "name": "exchange_id", "type": "str" } ], "request_body": { "schema_name": "ExchangeUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "code", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "timezone", "type": "str", "required": false, "nullable": true }, { "name": "trading_hours", "type": "str", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false, "nullable": true }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "ExchangeResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "code", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "timezone", "type": "str", "required": false }, { "name": "trading_hours", "type": "str", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/exchanges/{exchange_id}", "summary": "Delete Exchange", "description": "Deletes an exchange. Returns 404 if exchange not found, 409 if exchange is referenced by existing stocks.", "path_params": [ { "name": "exchange_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/stocks", "summary": "Create Stock", "description": "Creates a new stock record. Validates ticker symbol and company name uniqueness, sector and exchange existence, and price business rules (high >= low, open/close between low and high). Returns 400 for validation errors, 409 for conflicts.", "request_body": { "schema_name": "StockCreate", "fields": [ { "name": "ticker_symbol", "type": "str", "required": false }, { "name": "company_name", "type": "str", "required": false }, { "name": "current_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "opening_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "closing_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "high_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "low_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "volume", "type": "int", "required": false, "nullable": true }, { "name": "market_cap", "type": "Decimal", "required": false, "nullable": true }, { "name": "sector_id", "type": "str", "required": true }, { "name": "industry", "type": "str", "required": false, "nullable": true }, { "name": "exchange_id", "type": "str", "required": true }, { "name": "currency", "type": "str", "required": false }, { "name": "last_updated", "type": "datetime", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "ipo_date", "type": "date", "required": false, "nullable": true }, { "name": "status", "type": "StockStatus", "required": false, "enum_values": [ "ACTIVE", "INACTIVE" ] } ] }, "response": { "schema_name": "StockResponse", "fields": [ { "name": "ticker_symbol", "type": "str", "required": false }, { "name": "company_name", "type": "str", "required": false }, { "name": "current_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "opening_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "closing_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "high_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "low_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "volume", "type": "int", "required": false, "nullable": true }, { "name": "market_cap", "type": "Decimal", "required": false, "nullable": true }, { "name": "sector_id", "type": "str", "required": true }, { "name": "industry", "type": "str", "required": false, "nullable": true }, { "name": "exchange_id", "type": "str", "required": true }, { "name": "currency", "type": "str", "required": false }, { "name": "last_updated", "type": "datetime", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "ipo_date", "type": "date", "required": false, "nullable": true }, { "name": "status", "type": "StockStatus", "required": false, "enum_values": [ "ACTIVE", "INACTIVE" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/stocks", "summary": "List Stocks", "description": "Returns a paginated list of stocks ordered by ticker symbol. Supports search on ticker or company name, and filters by sector, exchange, status, and price range.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false }, { "name": "sector_id", "type": "str", "required": false }, { "name": "exchange_id", "type": "str", "required": false }, { "name": "status_filter", "type": "str", "required": false }, { "name": "min_price", "type": "Decimal", "required": false }, { "name": "max_price", "type": "Decimal", "required": false } ], "response": { "schema_name": "StockResponse", "fields": [ { "name": "ticker_symbol", "type": "str", "required": false }, { "name": "company_name", "type": "str", "required": false }, { "name": "current_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "opening_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "closing_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "high_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "low_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "volume", "type": "int", "required": false, "nullable": true }, { "name": "market_cap", "type": "Decimal", "required": false, "nullable": true }, { "name": "sector_id", "type": "str", "required": true }, { "name": "industry", "type": "str", "required": false, "nullable": true }, { "name": "exchange_id", "type": "str", "required": true }, { "name": "currency", "type": "str", "required": false }, { "name": "last_updated", "type": "datetime", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "ipo_date", "type": "date", "required": false, "nullable": true }, { "name": "status", "type": "StockStatus", "required": false, "enum_values": [ "ACTIVE", "INACTIVE" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/stocks/{stock_id}", "summary": "Get Stock", "description": "Retrieves a single stock by ID. Returns 404 if the stock does not exist.", "path_params": [ { "name": "stock_id", "type": "str" } ], "response": { "schema_name": "StockResponse", "fields": [ { "name": "ticker_symbol", "type": "str", "required": false }, { "name": "company_name", "type": "str", "required": false }, { "name": "current_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "opening_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "closing_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "high_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "low_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "volume", "type": "int", "required": false, "nullable": true }, { "name": "market_cap", "type": "Decimal", "required": false, "nullable": true }, { "name": "sector_id", "type": "str", "required": true }, { "name": "industry", "type": "str", "required": false, "nullable": true }, { "name": "exchange_id", "type": "str", "required": true }, { "name": "currency", "type": "str", "required": false }, { "name": "last_updated", "type": "datetime", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "ipo_date", "type": "date", "required": false, "nullable": true }, { "name": "status", "type": "StockStatus", "required": false, "enum_values": [ "ACTIVE", "INACTIVE" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/stocks/{stock_id}/details", "summary": "Get Stock Details", "description": "Retrieves a stock with eagerly loaded sector and exchange details. Returns 404 if the stock does not exist.", "path_params": [ { "name": "stock_id", "type": "str" } ], "response": { "schema_name": "StockDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "ticker_symbol", "type": "str", "required": true }, { "name": "company_name", "type": "str", "required": true }, { "name": "current_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "opening_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "closing_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "high_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "low_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "volume", "type": "int", "required": false, "nullable": true }, { "name": "market_cap", "type": "Decimal", "required": false, "nullable": true }, { "name": "industry", "type": "str", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": true }, { "name": "last_updated", "type": "datetime", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "ipo_date", "type": "date", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "sector", "type": "SectorResponse", "required": true, "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "icon_url", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "exchange", "type": "ExchangeResponse", "required": true, "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "code", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false }, { "name": "timezone", "type": "str", "required": false }, { "name": "trading_hours", "type": "str", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/stocks/{stock_id}/history", "summary": "Get Stock With History", "description": "Retrieves a stock with all historical price data eagerly loaded. Returns 404 if the stock does not exist.", "path_params": [ { "name": "stock_id", "type": "str" } ], "response": { "schema_name": "StockWithHistoryResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "ticker_symbol", "type": "str", "required": true }, { "name": "company_name", "type": "str", "required": true }, { "name": "current_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "stock_history", "type": "List[StockhistoryResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "stock_id", "type": "str", "required": true }, { "name": "date", "type": "date", "required": true }, { "name": "open_price", "type": "Decimal", "required": true }, { "name": "close_price", "type": "Decimal", "required": true }, { "name": "high_price", "type": "Decimal", "required": true }, { "name": "low_price", "type": "Decimal", "required": true }, { "name": "volume", "type": "int", "required": true }, { "name": "adjusted_close_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/stocks/search/autocomplete", "summary": "Search Stocks Autocomplete", "description": "Searches active stocks by ticker or company name for autocomplete suggestions. Returns up to 10 results. Requires at least 1 character search term.", "query_params": [ { "name": "search", "type": "str", "required": false, "default": null } ], "response": { "schema_name": "StockResponse", "fields": [ { "name": "ticker_symbol", "type": "str", "required": false }, { "name": "company_name", "type": "str", "required": false }, { "name": "current_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "opening_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "closing_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "high_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "low_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "volume", "type": "int", "required": false, "nullable": true }, { "name": "market_cap", "type": "Decimal", "required": false, "nullable": true }, { "name": "sector_id", "type": "str", "required": true }, { "name": "industry", "type": "str", "required": false, "nullable": true }, { "name": "exchange_id", "type": "str", "required": true }, { "name": "currency", "type": "str", "required": false }, { "name": "last_updated", "type": "datetime", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "ipo_date", "type": "date", "required": false, "nullable": true }, { "name": "status", "type": "StockStatus", "required": false, "enum_values": [ "ACTIVE", "INACTIVE" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/stocks/{stock_id}", "summary": "Update Stock", "description": "Updates an existing stock. Validates ticker and company name uniqueness if changed, sector and exchange existence, and price business rules. Updates last_updated timestamp. Returns 400 for validation errors, 404 if not found, 409 for conflicts.", "path_params": [ { "name": "stock_id", "type": "str" } ], "request_body": { "schema_name": "StockUpdate", "fields": [ { "name": "ticker_symbol", "type": "str", "required": false, "nullable": true }, { "name": "company_name", "type": "str", "required": false, "nullable": true }, { "name": "current_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "opening_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "closing_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "high_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "low_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "volume", "type": "int", "required": false, "nullable": true }, { "name": "market_cap", "type": "Decimal", "required": false, "nullable": true }, { "name": "sector_id", "type": "str", "required": false, "nullable": true }, { "name": "industry", "type": "str", "required": false, "nullable": true }, { "name": "exchange_id", "type": "str", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false, "nullable": true }, { "name": "last_updated", "type": "datetime", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "ipo_date", "type": "date", "required": false, "nullable": true }, { "name": "status", "type": "StockStatus", "required": false, "nullable": true, "enum_values": [ "ACTIVE", "INACTIVE" ] } ] }, "response": { "schema_name": "StockResponse", "fields": [ { "name": "ticker_symbol", "type": "str", "required": false }, { "name": "company_name", "type": "str", "required": false }, { "name": "current_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "opening_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "closing_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "high_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "low_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "volume", "type": "int", "required": false, "nullable": true }, { "name": "market_cap", "type": "Decimal", "required": false, "nullable": true }, { "name": "sector_id", "type": "str", "required": true }, { "name": "industry", "type": "str", "required": false, "nullable": true }, { "name": "exchange_id", "type": "str", "required": true }, { "name": "currency", "type": "str", "required": false }, { "name": "last_updated", "type": "datetime", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "ipo_date", "type": "date", "required": false, "nullable": true }, { "name": "status", "type": "StockStatus", "required": false, "enum_values": [ "ACTIVE", "INACTIVE" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/stocks/{stock_id}", "summary": "Delete Stock", "description": "Soft deletes a stock by marking its status as INACTIVE. Returns 404 if stock not found.", "path_params": [ { "name": "stock_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/stocks/bulk-import", "summary": "Bulk Import Stocks", "description": "Imports multiple stocks from a list. Validates each stock, checks sector and exchange existence, and ensures ticker and company name uniqueness. Returns a summary with total, successful, failed counts and error details. Maximum 10,000 rows per import.", "request_body": { "schema_name": "BulkImportStocksRequest", "fields": [ { "name": "stocks", "type": "List[BulkImportStockItem]", "required": true, "is_list": true, "item_fields": [ { "name": "ticker_symbol", "type": "str", "required": true }, { "name": "company_name", "type": "str", "required": true }, { "name": "sector_name", "type": "str", "required": true }, { "name": "exchange_code", "type": "str", "required": true }, { "name": "currency", "type": "str", "required": true }, { "name": "current_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "industry", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "ipo_date", "type": "date", "required": false, "nullable": true } ] } ] }, "response": { "schema_name": "BulkImportStocksResponse", "fields": [ { "name": "total", "type": "int", "required": true }, { "name": "successful", "type": "int", "required": true }, { "name": "failed", "type": "int", "required": true }, { "name": "errors", "type": "List[str]", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/stock-history", "summary": "Create Stock History", "description": "Creates a new stock history record. Validates stock existence, uniqueness of stock_id and date combination, and price business rules (high >= low, open/close between low and high). Returns 400 for validation errors, 409 for conflicts.", "request_body": { "schema_name": "StockhistoryCreate", "fields": [ { "name": "stock_id", "type": "str", "required": true }, { "name": "date", "type": "date", "required": true }, { "name": "open_price", "type": "Decimal", "required": true }, { "name": "close_price", "type": "Decimal", "required": true }, { "name": "high_price", "type": "Decimal", "required": true }, { "name": "low_price", "type": "Decimal", "required": true }, { "name": "volume", "type": "int", "required": true }, { "name": "adjusted_close_price", "type": "Decimal", "required": false, "nullable": true } ] }, "response": { "schema_name": "StockhistoryResponse", "fields": [ { "name": "stock_id", "type": "str", "required": true }, { "name": "date", "type": "date", "required": true }, { "name": "open_price", "type": "Decimal", "required": true }, { "name": "close_price", "type": "Decimal", "required": true }, { "name": "high_price", "type": "Decimal", "required": true }, { "name": "low_price", "type": "Decimal", "required": true }, { "name": "volume", "type": "int", "required": true }, { "name": "adjusted_close_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/stock-history", "summary": "List Stock History", "description": "Returns a paginated list of stock history records ordered by date descending. Supports filters by stock_id, start_date, and end_date.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "stock_id", "type": "str", "required": false }, { "name": "start_date", "type": "date", "required": false }, { "name": "end_date", "type": "date", "required": false } ], "response": { "schema_name": "StockhistoryResponse", "fields": [ { "name": "stock_id", "type": "str", "required": true }, { "name": "date", "type": "date", "required": true }, { "name": "open_price", "type": "Decimal", "required": true }, { "name": "close_price", "type": "Decimal", "required": true }, { "name": "high_price", "type": "Decimal", "required": true }, { "name": "low_price", "type": "Decimal", "required": true }, { "name": "volume", "type": "int", "required": true }, { "name": "adjusted_close_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/stock-history/{stockhistory_id}", "summary": "Get Stock History", "description": "Retrieves a single stock history record by ID. Returns 404 if the record does not exist.", "path_params": [ { "name": "stockhistory_id", "type": "str" } ], "response": { "schema_name": "StockhistoryResponse", "fields": [ { "name": "stock_id", "type": "str", "required": true }, { "name": "date", "type": "date", "required": true }, { "name": "open_price", "type": "Decimal", "required": true }, { "name": "close_price", "type": "Decimal", "required": true }, { "name": "high_price", "type": "Decimal", "required": true }, { "name": "low_price", "type": "Decimal", "required": true }, { "name": "volume", "type": "int", "required": true }, { "name": "adjusted_close_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/stock-history/{stockhistory_id}", "summary": "Update Stock History", "description": "Updates an existing stock history record. Validates stock existence if changed, uniqueness of stock_id and date if changed, and price business rules. Returns 400 for validation errors, 404 if not found, 409 for conflicts.", "path_params": [ { "name": "stockhistory_id", "type": "str" } ], "request_body": { "schema_name": "StockhistoryUpdate", "fields": [ { "name": "stock_id", "type": "str", "required": false, "nullable": true }, { "name": "date", "type": "date", "required": false, "nullable": true }, { "name": "open_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "close_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "high_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "low_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "volume", "type": "int", "required": false, "nullable": true }, { "name": "adjusted_close_price", "type": "Decimal", "required": false, "nullable": true } ] }, "response": { "schema_name": "StockhistoryResponse", "fields": [ { "name": "stock_id", "type": "str", "required": true }, { "name": "date", "type": "date", "required": true }, { "name": "open_price", "type": "Decimal", "required": true }, { "name": "close_price", "type": "Decimal", "required": true }, { "name": "high_price", "type": "Decimal", "required": true }, { "name": "low_price", "type": "Decimal", "required": true }, { "name": "volume", "type": "int", "required": true }, { "name": "adjusted_close_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/stock-history/{stockhistory_id}", "summary": "Delete Stock History", "description": "Deletes a stock history record. Returns 404 if the record does not exist.", "path_params": [ { "name": "stockhistory_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/stock-history/bulk-import", "summary": "Bulk Import Stock History", "description": "Imports multiple stock history records from a list. Validates each record, checks stock existence by ticker symbol, ensures uniqueness of stock and date combination, and validates price business rules. Returns a summary with total, successful, failed counts and error details. Maximum 10,000 rows per import.", "request_body": { "schema_name": "BulkImportHistoryRequest", "fields": [ { "name": "history_items", "type": "List[BulkImportHistoryItem]", "required": true, "is_list": true, "item_fields": [ { "name": "ticker_symbol", "type": "str", "required": true }, { "name": "date", "type": "date", "required": true }, { "name": "open_price", "type": "Decimal", "required": true }, { "name": "close_price", "type": "Decimal", "required": true }, { "name": "high_price", "type": "Decimal", "required": true }, { "name": "low_price", "type": "Decimal", "required": true }, { "name": "volume", "type": "int", "required": true }, { "name": "adjusted_close_price", "type": "Decimal", "required": false, "nullable": true } ] } ] }, "response": { "schema_name": "BulkImportHistoryResponse", "fields": [ { "name": "total", "type": "int", "required": true }, { "name": "successful", "type": "int", "required": true }, { "name": "failed", "type": "int", "required": true }, { "name": "errors", "type": "List[str]", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "User Management", "prefix": "/users", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create User", "description": "Creates a new user account. Validates email uniqueness and password strength. Returns 409 if email already exists. Passwords must be at least 8 characters with 1 uppercase, 1 lowercase, and 1 number.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": false, "enum_values": [ "ANONYMOUS", "REGISTERED", "DATA_MANAGER", "ADMINISTRATOR" ] }, { "name": "status", "type": "UserStatus", "required": false, "enum_values": [ "ACTIVE", "INACTIVE", "SUSPENDED" ] }, { "name": "profile_picture_url", "type": "str", "required": false, "nullable": true }, { "name": "preferences", "type": "dict", "required": false, "nullable": true }, { "name": "password", "type": "str", "required": true } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "registration_date", "type": "datetime", "required": true }, { "name": "last_login_date", "type": "datetime", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "profile_picture_url", "type": "str", "required": false, "nullable": true }, { "name": "preferences", "type": "dict", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Users", "description": "Returns a paginated list of users. Supports optional filters for role, status, and search by email or name. Search is case-insensitive and matches partial strings.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "role", "type": "str", "required": false }, { "name": "status", "type": "str", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "registration_date", "type": "datetime", "required": true }, { "name": "last_login_date", "type": "datetime", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "profile_picture_url", "type": "str", "required": false, "nullable": true }, { "name": "preferences", "type": "dict", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{user_id}", "summary": "Get User", "description": "Retrieves a single user by ID. Returns 404 if user does not exist.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "registration_date", "type": "datetime", "required": true }, { "name": "last_login_date", "type": "datetime", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "profile_picture_url", "type": "str", "required": false, "nullable": true }, { "name": "preferences", "type": "dict", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{user_id}", "summary": "Update User", "description": "Updates an existing user. All fields are optional. Validates email uniqueness if email is changed. Returns 404 if user not found, 409 if new email already exists.", "path_params": [ { "name": "user_id", "type": "str" } ], "request_body": { "schema_name": "UserUpdate", "fields": [ { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": false, "nullable": true, "enum_values": [ "ANONYMOUS", "REGISTERED", "DATA_MANAGER", "ADMINISTRATOR" ] }, { "name": "status", "type": "UserStatus", "required": false, "nullable": true, "enum_values": [ "ACTIVE", "INACTIVE", "SUSPENDED" ] }, { "name": "profile_picture_url", "type": "str", "required": false, "nullable": true }, { "name": "preferences", "type": "dict", "required": false, "nullable": true }, { "name": "password", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "registration_date", "type": "datetime", "required": true }, { "name": "last_login_date", "type": "datetime", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "profile_picture_url", "type": "str", "required": false, "nullable": true }, { "name": "preferences", "type": "dict", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{user_id}", "summary": "Delete User", "description": "Deletes a user account. Administrator accounts cannot be deleted. Returns 400 if attempting to delete an administrator, 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/register", "summary": "Register New User", "description": "Registers a new user account with email and password. Validates email uniqueness and password strength. Automatically assigns REGISTERED role and ACTIVE status. Returns 409 if email already exists.", "request_body": { "schema_name": "UserRegister", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": false, "enum_values": [ "ANONYMOUS", "REGISTERED", "DATA_MANAGER", "ADMINISTRATOR" ] }, { "name": "status", "type": "UserStatus", "required": false, "enum_values": [ "ACTIVE", "INACTIVE", "SUSPENDED" ] }, { "name": "profile_picture_url", "type": "str", "required": false, "nullable": true }, { "name": "preferences", "type": "dict", "required": false, "nullable": true }, { "name": "password", "type": "str", "required": true } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "registration_date", "type": "datetime", "required": true }, { "name": "last_login_date", "type": "datetime", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "profile_picture_url", "type": "str", "required": false, "nullable": true }, { "name": "preferences", "type": "dict", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "POST", "path": "/login", "summary": "Authenticate User", "description": "Authenticates a user with email and password. Validates credentials and account status. Updates last login timestamp. Returns 400 if credentials invalid or account is suspended/inactive.", "request_body": { "schema_name": "UserLogin", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "password", "type": "str", "required": true } ] }, "status_code": 200 }, { "method": "POST", "path": "/logout", "summary": "Log Out User", "description": "Logs out the current user. In a production system, this would invalidate the JWT token. Returns success message.", "status_code": 200 }, { "method": "POST", "path": "/activities", "summary": "Create User Activity", "description": "Logs a user activity (view, search, or favorite) for a stock. Validates that both user and stock exist. Returns 404 if user or stock not found.", "request_body": { "schema_name": "UseractivityCreate", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "activity_type", "type": "ActivityType", "required": true, "enum_values": [ "VIEW", "SEARCH", "FAVORITE" ] }, { "name": "session_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "UseractivityResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "activity_type", "type": "str", "required": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "session_id", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/activities/list", "summary": "List User Activities", "description": "Returns a paginated list of user activities. Supports optional filters for user_id, stock_id, activity_type, and session_id. Results are ordered by timestamp descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "stock_id", "type": "str", "required": false }, { "name": "activity_type", "type": "str", "required": false }, { "name": "session_id", "type": "str", "required": false } ], "response": { "schema_name": "UseractivityResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "activity_type", "type": "str", "required": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "session_id", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/activities/{activity_id}", "summary": "Get User Activity", "description": "Retrieves a single user activity by ID. Returns 404 if activity does not exist.", "path_params": [ { "name": "activity_id", "type": "str" } ], "response": { "schema_name": "UseractivityResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "activity_type", "type": "str", "required": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "session_id", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/activities/{activity_id}", "summary": "Update User Activity", "description": "Updates an existing user activity. All fields are optional. Validates user and stock existence if those fields are updated. Returns 404 if activity, user, or stock not found.", "path_params": [ { "name": "activity_id", "type": "str" } ], "request_body": { "schema_name": "UseractivityUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "stock_id", "type": "str", "required": false, "nullable": true }, { "name": "activity_type", "type": "ActivityType", "required": false, "nullable": true, "enum_values": [ "VIEW", "SEARCH", "FAVORITE" ] }, { "name": "timestamp", "type": "datetime", "required": false, "nullable": true }, { "name": "session_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "UseractivityResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "activity_type", "type": "str", "required": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "session_id", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/activities/{activity_id}", "summary": "Delete User Activity", "description": "Deletes a user activity record. Returns 404 if activity not found.", "path_params": [ { "name": "activity_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{user_id}/activities", "summary": "Get User Activities With Stock Details", "description": "Retrieves all activities for a specific user with associated stock details (ticker, company name, current price). Results are paginated and ordered by timestamp descending. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "UseractivityWithStock", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "activity_type", "type": "str", "required": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "session_id", "type": "str", "required": false, "nullable": true }, { "name": "stock", "type": "StockBasicInfo", "required": true, "fields": [ { "name": "ticker_symbol", "type": "str", "required": true }, { "name": "company_name", "type": "str", "required": true }, { "name": "current_price", "type": "float", "required": false, "nullable": true } ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "POST", "path": "/activities/log", "summary": "Log User Activity", "description": "Convenience endpoint to log a user activity (view, search, or favorite) for a stock. Automatically sets timestamp to current time. Validates that both user and stock exist. Returns 404 if user or stock not found.", "query_params": [ { "name": "session_id", "type": "str", "required": false } ], "response": { "schema_name": "UseractivityResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "activity_type", "type": "str", "required": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "session_id", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 } ] }, { "name": "Watchlists", "prefix": "/watchlists", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Watchlist", "description": "Creates a new watchlist for a user. Validates that the user exists, the watchlist name is unique per user, and the user has not exceeded the maximum of 10 watchlists. Returns 404 if user not found, 409 if name already exists, or 400 if limit exceeded.", "request_body": { "schema_name": "WatchlistCreate", "fields": [ { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_default", "type": "bool", "required": false, "default": false }, { "name": "sort_order", "type": "int", "required": true }, { "name": "user_id", "type": "str", "required": true } ] }, "response": { "schema_name": "WatchlistResponse", "fields": [ { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_default", "type": "bool", "required": false, "default": false }, { "name": "sort_order", "type": "int", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Watchlists", "description": "Returns a paginated list of watchlists. Supports optional filtering by user_id and is_default flag. Results are ordered by sort_order ascending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "is_default", "type": "bool", "required": false } ], "response": { "schema_name": "WatchlistResponse", "fields": [ { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_default", "type": "bool", "required": false, "default": false }, { "name": "sort_order", "type": "int", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{watchlist_id}", "summary": "Get Watchlist", "description": "Retrieves a single watchlist by ID. Returns 404 if the watchlist does not exist.", "path_params": [ { "name": "watchlist_id", "type": "str" } ], "response": { "schema_name": "WatchlistResponse", "fields": [ { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_default", "type": "bool", "required": false, "default": false }, { "name": "sort_order", "type": "int", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{watchlist_id}", "summary": "Update Watchlist", "description": "Updates a watchlist's details. Only provided fields are updated. Validates that the new name (if provided) is unique per user. Returns 404 if watchlist not found or 409 if name conflict.", "path_params": [ { "name": "watchlist_id", "type": "str" } ], "request_body": { "schema_name": "WatchlistUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_default", "type": "bool", "required": false, "nullable": true }, { "name": "sort_order", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "WatchlistResponse", "fields": [ { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_default", "type": "bool", "required": false, "default": false }, { "name": "sort_order", "type": "int", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{watchlist_id}", "summary": "Delete Watchlist", "description": "Deletes a watchlist and all its associated watchlist items. Validates that the watchlist is not marked as default. Returns 404 if watchlist not found or 400 if attempting to delete default watchlist.", "path_params": [ { "name": "watchlist_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{watchlist_id}/details", "summary": "Get Watchlist With Details", "description": "Retrieves a watchlist with all its stocks and their details including sector and exchange information. Uses eager loading to prevent N+1 queries. Returns 404 if watchlist not found.", "path_params": [ { "name": "watchlist_id", "type": "str" } ], "response": { "schema_name": "WatchlistDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_default", "type": "bool", "required": true }, { "name": "sort_order", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "watchlist_items", "type": "List[WatchlistitemDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "str", "required": true }, { "name": "watchlist_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "added_date", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "sort_order", "type": "int", "required": true }, { "name": "stock", "type": "StockInWatchlistResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "ticker_symbol", "type": "str", "required": true }, { "name": "company_name", "type": "str", "required": true }, { "name": "current_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "sector_name", "type": "str", "required": false, "nullable": true }, { "name": "exchange_name", "type": "str", "required": false, "nullable": true } ] } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{watchlist_id}/add-stock", "summary": "Add Stock To Watchlist", "description": "Adds a stock to a watchlist. Validates that the watchlist and stock exist, the stock is not already in the watchlist, and the watchlist has not exceeded the maximum of 100 stocks. Returns 404 if watchlist or stock not found, 409 if stock already exists in watchlist, or 400 if limit exceeded.", "path_params": [ { "name": "watchlist_id", "type": "str" } ], "query_params": [ { "name": "stock_id", "type": "str", "required": false, "default": null }, { "name": "notes", "type": "str", "required": false } ], "response": { "schema_name": "WatchlistitemResponse", "fields": [ { "name": "watchlist_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "added_date", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "sort_order", "type": "int", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "DELETE", "path": "/{watchlist_id}/remove-stock/{stock_id}", "summary": "Remove Stock From Watchlist", "description": "Removes a stock from a watchlist. Returns 404 if the watchlist or stock association does not exist.", "path_params": [ { "name": "watchlist_id", "type": "str" }, { "name": "stock_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/items", "summary": "Create Watchlist Item", "description": "Creates a new watchlist item linking a stock to a watchlist. Validates that the watchlist and stock exist, the stock is not already in the watchlist, and the watchlist has not exceeded the maximum of 100 stocks. Returns 404 if watchlist or stock not found, 409 if stock already exists in watchlist, or 400 if limit exceeded.", "request_body": { "schema_name": "WatchlistitemCreate", "fields": [ { "name": "watchlist_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "added_date", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "sort_order", "type": "int", "required": true } ] }, "response": { "schema_name": "WatchlistitemResponse", "fields": [ { "name": "watchlist_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "added_date", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "sort_order", "type": "int", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/items", "summary": "List Watchlist Items", "description": "Returns a paginated list of watchlist items. Supports optional filtering by watchlist_id and stock_id. Results are ordered by sort_order ascending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "watchlist_id", "type": "str", "required": false }, { "name": "stock_id", "type": "str", "required": false } ], "response": { "schema_name": "WatchlistitemResponse", "fields": [ { "name": "watchlist_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "added_date", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "sort_order", "type": "int", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/items/{item_id}", "summary": "Get Watchlist Item", "description": "Retrieves a single watchlist item by ID. Returns 404 if the item does not exist.", "path_params": [ { "name": "item_id", "type": "str" } ], "response": { "schema_name": "WatchlistitemResponse", "fields": [ { "name": "watchlist_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "added_date", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "sort_order", "type": "int", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/items/{item_id}", "summary": "Update Watchlist Item", "description": "Updates a watchlist item's details (notes and sort_order). Only provided fields are updated. Returns 404 if item not found.", "path_params": [ { "name": "item_id", "type": "str" } ], "request_body": { "schema_name": "WatchlistitemUpdate", "fields": [ { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "sort_order", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "WatchlistitemResponse", "fields": [ { "name": "watchlist_id", "type": "str", "required": true }, { "name": "stock_id", "type": "str", "required": true }, { "name": "added_date", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "sort_order", "type": "int", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/items/{item_id}", "summary": "Delete Watchlist Item", "description": "Deletes a watchlist item, removing the stock from the watchlist. Returns 404 if item not found.", "path_params": [ { "name": "item_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "System Configuration", "prefix": "/system-configurations", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create System Configuration", "description": "Creates a new system configuration record. Validates that the configuration key is unique. Returns 409 if the key already exists. Returns 400 if the modified_by_user_id references a non-existent user.", "request_body": { "schema_name": "SystemconfigurationCreate", "fields": [ { "name": "key", "type": "str", "required": false }, { "name": "value", "type": "str", "required": true }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "BOOLEAN", "JSON", "DECIMAL" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "modified_by_user_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "SystemconfigurationResponse", "fields": [ { "name": "key", "type": "str", "required": false }, { "name": "value", "type": "str", "required": true }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "BOOLEAN", "JSON", "DECIMAL" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "modified_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "last_modified_date", "type": "datetime", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List System Configurations", "description": "Returns a paginated list of system configurations. Supports optional search filter on key and description fields, and optional data_type filter. Results are ordered by key in ascending order.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false }, { "name": "data_type", "type": "ConfigDataType", "required": false } ], "response": { "schema_name": "SystemconfigurationResponse", "fields": [ { "name": "key", "type": "str", "required": false }, { "name": "value", "type": "str", "required": true }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "BOOLEAN", "JSON", "DECIMAL" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "modified_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "last_modified_date", "type": "datetime", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/by-key/{key}", "summary": "Get System Configuration By Key", "description": "Retrieves a system configuration by its unique key. Returns 404 if the configuration key does not exist.", "path_params": [ { "name": "key", "type": "str" } ], "response": { "schema_name": "SystemconfigurationResponse", "fields": [ { "name": "key", "type": "str", "required": false }, { "name": "value", "type": "str", "required": true }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "BOOLEAN", "JSON", "DECIMAL" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "modified_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "last_modified_date", "type": "datetime", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{id}", "summary": "Get System Configuration", "description": "Retrieves a system configuration by its unique identifier. Returns 404 if the configuration does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "SystemconfigurationResponse", "fields": [ { "name": "key", "type": "str", "required": false }, { "name": "value", "type": "str", "required": true }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "BOOLEAN", "JSON", "DECIMAL" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "modified_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "last_modified_date", "type": "datetime", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{id}/details", "summary": "Get System Configuration With Details", "description": "Retrieves a system configuration with related user details (modified_by_user). Returns 404 if the configuration does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "SystemconfigurationResponse", "fields": [ { "name": "key", "type": "str", "required": false }, { "name": "value", "type": "str", "required": true }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "BOOLEAN", "JSON", "DECIMAL" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "modified_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "last_modified_date", "type": "datetime", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update System Configuration", "description": "Updates an existing system configuration. Validates that the new key (if provided) is unique. Returns 404 if the configuration does not exist. Returns 409 if the new key conflicts with an existing configuration. Returns 400 if the modified_by_user_id references a non-existent user.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "SystemconfigurationUpdate", "fields": [ { "name": "key", "type": "str", "required": false, "nullable": true }, { "name": "value", "type": "str", "required": false, "nullable": true }, { "name": "data_type", "type": "ConfigDataType", "required": false, "nullable": true, "enum_values": [ "STRING", "INTEGER", "BOOLEAN", "JSON", "DECIMAL" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "modified_by_user_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "SystemconfigurationResponse", "fields": [ { "name": "key", "type": "str", "required": false }, { "name": "value", "type": "str", "required": true }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "BOOLEAN", "JSON", "DECIMAL" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "modified_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "last_modified_date", "type": "datetime", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete System Configuration", "description": "Deletes a system configuration by its unique identifier. Returns 404 if the configuration does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 } ] } ], "enums": { "StockStatus": [ "ACTIVE", "INACTIVE" ], "UserRole": [ "ANONYMOUS", "REGISTERED", "DATA_MANAGER", "ADMINISTRATOR" ], "UserStatus": [ "ACTIVE", "INACTIVE", "SUSPENDED" ], "ActivityType": [ "VIEW", "SEARCH", "FAVORITE" ], "ConfigDataType": [ "STRING", "INTEGER", "BOOLEAN", "JSON", "DECIMAL" ] } }