{"openapi":"3.1.0","info":{"title":"0Dhan - Stock Trading Simulation Platform API","description":"A comprehensive API for managing a stock trading platform, providing real-time stock data, user portfolio management, order processing, notifications, and reporting functionalities.","contact":{"email":"ganeshchandra.s@cognitree.com"},"version":"1.0"},"externalDocs":{"description":"Find out more about 0Dhan","url":"https://docs.google.com/document/d/1nRa6-X-pJyzOqzud9r3a27yC8TlnCo3gMUpwOFLUUJc/edit?usp=sharing"},"security":[{"basicAuth":[]}],"tags":[{"name":"User","description":"Handles user registration, profile management, and login functionalities."},{"name":"Stock","description":"Fetches and provides real-time stock market data."},{"name":"Watch List","description":"Allows users to create, update, delete, and manage their stock watchlists."},{"name":"Order","description":"Manages the placing, updating, and execution of orders."},{"name":"Portfolio","description":"Tracks user’s portfolio, providing analysis and aggregated details."},{"name":"Notification","description":"Manages notifications to users."}],"paths":{"/api/v1/users/{userId}":{"get":{"summary":"Get user details","tags":["User"],"operationId":"getUserDetails","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"User details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden to get user details with given Id"},"404":{"description":"User not found"}}},"delete":{"summary":"Get user details","tags":["User"],"operationId":"deleteUser","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"User deleted successfully"},"401":{"description":"Unauthorized"},"404":{"description":"userId not found"}}},"patch":{"summary":"Update user details","tags":["User"],"operationId":"updateUserDetails","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Update an existent user data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"responses":{"200":{"description":"User details Updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"description":"Invalid User details"},"401":{"description":"Unauthorized"},"404":{"description":"userId not found"}}}},"/api/v1/users":{"get":{"summary":"Get users list","tags":["User"],"operationId":"getUsersList","parameters":[{"name":"page","in":"query","description":"The page number to retrieve","required":false,"schema":{"type":"integer","examples":[1]}},{"name":"pageSize","in":"query","description":"The number of users to retrieve per page(limit:100)","required":false,"schema":{"type":"integer","examples":[10]}},{"name":"sortBy","in":"query","description":"The field to sort by (e.g., username, email, createdAt)","required":false,"schema":{"type":"string","enum":["username","email","createdAt"],"examples":["username"]}},{"name":"sortOrder","in":"query","description":"The order to sort the results in (ascending or descending)","required":false,"schema":{"type":"string","enum":["asc","desc"],"examples":["asc"]}},{"name":"username","in":"query","description":"filters users by name with the given string","required":false,"schema":{"type":"string"}},{"name":"email","in":"query","description":"filters users by email with the given string","required":false,"schema":{"type":"string"}},{"name":"createdAfter","in":"query","description":"filters users with given timestamp by created at","required":false,"schema":{"type":"string"}},{"name":"createdBefore","in":"query","description":"filters users with given timestamp by created at","required":false,"schema":{"type":"string"}},{"name":"modifiedAfter","in":"query","description":"filters users with given timestamp by updated at","required":false,"schema":{"type":"string"}},{"name":"modifiedBefore","in":"query","description":"filters users with given timestamp by updated at","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Users list retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"totalPages":{"type":"integer","description":"Total number of pages","examples":[5]},"currentPage":{"type":"integer","description":"The current page number","examples":[1]},"pageSize":{"type":"integer","description":"Number of users per page","examples":[10]},"totalItems":{"type":"integer","description":"Total number of users","examples":[50]},"userList":{"type":"array","items":{"$ref":"#/components/schemas/UserResponse"}}}}}}},"400":{"description":"Invalid page number/size provided"},"401":{"description":"Unauthorized"}}},"post":{"summary":"Create a new user","tags":["User"],"operationId":"createUser","requestBody":{"description":"Create a user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"responses":{"201":{"description":"User created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"400":{"description":"Invalid User details"}}}},"/api/v1/stocks/{stockId}":{"get":{"summary":"Retrieve data for a specific stock","tags":["Stock"],"operationId":"getStockData","parameters":[{"name":"stockId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stock details retrived successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stock"}}}},"404":{"description":"stockId not found"},"401":{"description":"Unauthorized"}}}},"/api/v1/watch-lists":{"post":{"summary":"Create a new watchlist","tags":["Watch List"],"operationId":"createWatchlist","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/WatchListRequest"}}}},"responses":{"201":{"description":"Watchlist created successfully","content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/WatchList"}}}},"400":{"description":"Invalid Watchlist details supplied"},"401":{"description":"Unauthorized"}}},"get":{"summary":"Retrieve all watchlists for a user","tags":["Watch List"],"operationId":"getWatchlists","parameters":[{"name":"page","in":"query","description":"The page number to retrieve","required":false,"schema":{"type":"integer","examples":[1]}},{"name":"pageSize","in":"query","description":"The number of watchlists to retrieve per page(limit:20)","required":false,"schema":{"type":"integer","examples":[10]}},{"name":"sortBy","in":"query","description":"Sort by specific fields (e.g., name, creationDate)","required":false,"schema":{"type":"string","examples":["-creationDate"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"examples":["asc"]},"description":"The order to sort the results in (ascending or descending)"},{"name":"name","in":"query","description":"filters watchLists by name containing specified string","required":false,"schema":{"type":"string"}},{"name":"createdAfter","in":"query","description":"filters watch-list with given timestamp by created at","required":false,"schema":{"type":"string"}},{"name":"createdBefore","in":"query","description":"filters watch-list with given timestamp by created at","required":false,"schema":{"type":"string"}},{"name":"modifiedAfter","in":"query","description":"filters watch-list with given timestamp by updated at","required":false,"schema":{"type":"string"}},{"name":"modifiedBefore","in":"query","description":"filters watch-list with given timestamp by updated at","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Watchlists retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"totalPages":{"type":"integer","description":"Total number of pages","examples":[5]},"currentPage":{"type":"integer","description":"The current page number","examples":[1]},"pageSize":{"type":"integer","description":"Number of watchlists per page","examples":[10]},"totalItems":{"type":"integer","description":"Total number of watchlists","examples":[50]},"watchlistList":{"type":"array","items":{"$ref":"#/components/schemas/WatchList"}}}}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/watch-lists/{watchlistId}":{"put":{"summary":"Update a specific watchlist","tags":["Watch List"],"operationId":"updateWatchlist","parameters":[{"name":"watchlistId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Update an existent watchlist data","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchList"}}}},"responses":{"200":{"description":"Watchlist updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchList"}}}},"400":{"description":"Invalid watchList details provided"},"401":{"description":"Unauthorized"},"404":{"description":"WatchListId Not Found"}}},"get":{"summary":"get a specific watchlist","tags":["Watch List"],"operationId":"gegtWatchlist","parameters":[{"name":"watchlistId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Watchlist retrived successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchList"}}}},"401":{"description":"Unauthorized"},"404":{"description":"WatchListId Not Found"}}},"delete":{"summary":"Delete a specific watchlist","tags":["Watch List"],"operationId":"deleteWatchlist","parameters":[{"name":"watchlistId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Watchlist deleted successfully"},"401":{"description":"Unauthorized"},"404":{"description":"Watchlist not found"}}}},"/api/v1/orders/{orderId}":{"get":{"summary":"Retrieve details of a specific order","tags":["Order"],"operationId":"getOrderDetails","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"Unauthorized"},"404":{"description":"OrderId not found"}}},"put":{"summary":"Update an existing order","tags":["Order"],"operationId":"updateOrder","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Update an existing order","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"responses":{"200":{"description":"Order updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Invalid order data provided"},"401":{"description":"Unauthorized"},"404":{"description":"OrderId not found"}}},"delete":{"summary":"delete an order","tags":["Order"],"operationId":"deleteOrder","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Order deleted successfully"},"401":{"description":"Unauthorized"},"404":{"description":"OrderId not found"}}}},"/api/v1/orders":{"post":{"summary":"Place a new market order","tags":["Order"],"operationId":"placeOrder","requestBody":{"description":"Place a new market order","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"responses":{"201":{"description":"Order placed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Invalid Order data provided"},"401":{"description":"Unauthorized"}}},"get":{"summary":"Retrieve list of orders","tags":["Order"],"operationId":"getOrders","parameters":[{"name":"page","in":"query","schema":{"type":"integer","examples":[1]},"description":"The page number to retrieve"},{"name":"pageSize","in":"query","schema":{"type":"integer","examples":[10]},"description":"The number of orders to retrieve per page"},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["date","price","status"],"examples":["date"]},"description":"The field to sort by (e.g., date, price, status)"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"examples":["asc"]},"description":"The order to sort the results in (ascending or descending)"},{"name":"status","in":"query","description":"filters by status contains given string","required":false,"schema":{"type":"string"}},{"name":"priceGT","in":"query","description":"filters orders by price with given value","required":false,"schema":{"type":"string"}},{"name":"priceLT","in":"query","description":"filters orders by price with given value","required":false,"schema":{"type":"string"}},{"name":"createdAfter","in":"query","description":"filters orders with given timestamp by created at","required":false,"schema":{"type":"string"}},{"name":"createdBefore","in":"query","description":"filters orders with given timestamp by created at","required":false,"schema":{"type":"string"}},{"name":"modifiedAfter","in":"query","description":"filters orders with given timestamp by updated at","required":false,"schema":{"type":"string"}},{"name":"modifiedBefore","in":"query","description":"filters orders with given timestamp by updated at","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Orders retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"totalItems":{"type":"integer","examples":[50]},"totalPages":{"type":"integer","examples":[5]},"currentPage":{"type":"integer","exampls":[1]},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}},"400":{"description":"Invalid pagination parameters"},"401":{"description":"Unauthorized"},"404":{"description":"Page not found"}}}},"/api/v1/portfolio":{"get":{"summary":"Retrieve current portfolio details","tags":["Portfolio"],"operationId":"getPortfolio","responses":{"200":{"description":"Portfolio details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Portfolio"}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/notifications":{"get":{"summary":"get notification List","tags":["Notification"],"operationId":"getNotificationList","parameters":[{"name":"page","in":"query","description":"The page number to retrieve","required":false,"schema":{"type":"integer","examples":[1]}},{"name":"pageSize","in":"query","description":"The number of notifications to retrieve per page","required":false,"schema":{"type":"integer","examples":[10]}},{"name":"sortBy","in":"query","description":"The field to sort by (e.g., status, notificationId)","required":false,"schema":{"type":"string","enum":["status","notificationId"],"examples":["status"]}},{"name":"sortOrder","in":"query","description":"The order to sort the results in (ascending or descending)","required":false,"schema":{"type":"string","enum":["asc","desc"],"examples":["asc"]}},{"name":"createdAfter","in":"query","description":"filters by created at with given timestamp","required":false,"schema":{"type":"string"}},{"name":"createdBefore","in":"query","description":"filters by created at with given timestamp","required":false,"schema":{"type":"string"}},{"name":"modifiedAfter","in":"query","description":"filters by updated at with given timestamp","required":false,"schema":{"type":"string"}},{"name":"modifiedBefore","in":"query","description":"filters by updated at with given timestamp","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"filters by status contains given string","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"NotificationList retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"totalPages":{"type":"integer","description":"Total number of pages","examples":[5]},"currentPage":{"type":"integer","description":"The current page number","examples":[1]},"pageSize":{"type":"integer","description":"Number of notifications per page","examples":[10]},"totalItems":{"type":"integer","description":"Total number of notifications","examples":[50]},"notifications":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}}}}}}},"400":{"description":"Invalid page number or page size provided"},"401":{"description":"Unauthorized"}}},"patch":{"summary":"Update notification","tags":["Notification"],"operationId":"updateNotification","requestBody":{"description":"Update notification status","required":true,"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/Notification"}}}},"responses":{"200":{"description":"notification updated successfully","content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/Notification"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Invalid notificationId provided"}}}},"/api/v1/notifications/{notificationId}":{"get":{"summary":"get notification","tags":["Notification"],"operationId":"getNotification","parameters":[{"name":"notificationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"notification retrived successfully","content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/Notification"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Invalid notificationId provided"}}},"delete":{"summary":"delete notification","tags":["Notification"],"operationId":"deleteNotification","parameters":[{"name":"notificationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"notification deleted successfully"},"401":{"description":"Unauthorized"},"404":{"description":"Invalid notificationId provided"}}}}},"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"schemas":{"User":{"type":"object","properties":{"userId":{"type":"integer","examples":[12345]},"emailId":{"type":"string","format":"email","examples":["user@example.com"]},"name":{"type":"string","examples":["John Doe"]},"password":{"type":"string","format":"password","examples":["encrypted_password"]}}},"UserResponse":{"type":"object","properties":{"userId":{"type":"integer","examples":[12345]},"emailId":{"type":"string","format":"email","examples":["user@example.com"]},"name":{"type":"string","examples":["John Doe"]}}},"Notification":{"type":"object","properties":{"notificationId":{"type":"integer","examples":[1]},"userId":{"type":"integer","examples":[12345]},"notificationType":{"type":"string","examples":["Alert"]},"status":{"type":"string","examples":["Read"]},"notificationData":{"type":"string","examples":["Notification information"]}}},"WatchListRequest":{"type":"object","properties":{"userId":{"type":"integer","examples":[12345]},"stockIdList":{"type":"array","items":{"type":"integer"},"examples":[["INFY","NIIT","LTI"]]},"watchListName":{"type":"string","examples":["Tech Stocks"]}}},"WatchList":{"type":"object","properties":{"watchListId":{"type":"integer","examples":[1]},"userId":{"type":"integer","examples":[12345]},"stockIdList":{"type":"array","items":{"type":"integer"},"examples":[["INFY","NIIT","LTI"]]},"watchListName":{"type":"string","examples":["Tech Stocks"]}}},"Portfolio":{"type":"object","properties":{"portfolioId":{"type":"integer","examples":[1]},"userId":{"type":"integer","examples":[12345]},"totalProfitLoss":{"type":"number","format":"float","examples":[1500.75]},"profitLossPercent":{"type":"number","format":"float","examples":[5.5]},"portfolioStockList":{"type":"array","items":{"type":"object","properties":{"stockId":{"type":"integer","examples":[101]},"averageBuyPrice":{"type":"number","format":"float","examples":[150.25]},"quantity":{"type":"integer","examples":[10]},"currentStockPrice":{"type":"number","format":"float","examples":[155.25]},"timestamp":{"type":"number","format":"float","examples":[1689889843]}}}}}},"Order":{"type":"object","properties":{"userId":{"type":"integer","examples":[12345]},"stockId":{"type":"integer","examples":[101]},"orderId":{"type":"integer","examples":[1001]},"stockPrice":{"type":"number","format":"float","examples":[250.75]},"stockQuantity":{"type":"integer","examples":[10]},"orderStatus":{"type":"string","examples":["Completed"]},"orderType":{"type":"string","examples":["Buy"]}}},"Stock":{"type":"object","properties":{"stockId":{"type":"integer","description":"Unique identifier for the stock.","examples":[101]},"tickerSymbol":{"type":"string","description":"The stock's ticker symbol.","examples":["AAPL"]},"companyName":{"type":"string","description":"The name of the company associated with the stock.","examples":["Apple Inc."]},"currentPrice":{"type":"number","format":"float","description":"The current trading price of the stock.","examples":[175.5]},"timestamp":{"type":"number","format":"float","description":"Timestamp at which current trading price of the stock retrived.","examples":[168950123]},"marketCap":{"type":"number","format":"float","description":"The market capitalization of the company in billions.","examples":[2500.75]},"sector":{"type":"string","description":"The market sector the company operates in.","examples":["Technology"]},"exchange":{"type":"string","description":"The stock exchange where the stock is traded.","examples":["NASDAQ"]}}}}}}