-
Notifications
You must be signed in to change notification settings - Fork 0
API Documentation
Let's an existing user login by sending its username and password. Attaches auth cookies to the response.
POST api/login
{
"username": "",
"password": ""
}{
"message": "Login successful",
"username": "",
"user_id": "",
"name": "",
"surname": "",
"email": "",
"labels": ""
}{
"error": "Invalid username or password",
}Let's a user register to Spot On.
POST api/register
{
"name": "",
"surname": "",
"username": "",
"email": "",
"password": "",
"labels": ""
}{
"message": "Registration successful",
"username": "",
"user_id": "",
"name": "",
"surname": "",
"email": "",
"labels": ""
}{
"error": "Username already exists"
}{
"error": "Email already registered"
}Initializes the "forgot password" workflow. When this endpoint is called, if the user with the email provided exists, the user gets an email that has a link to the password reset page.
POST api/forget-password
{
"email": ""
}{
"success": "We have sent you a link to reset your password"
}{
"error": "User with credentials not found"
}The second part of the "forget password" workflow. The request must have a valid "reset token". The "reset token" is only given to the user via an email, that has the reset token embedded in the spotonapp.win url.
POST api/reset-password
{
"token": "",
"new_password": "",
"confirm_password": ""
}{
"success": "Password updated"
}{
"error": "Passwords do not match"
}{
"error": "No user found"
}Gets the current authenticated user.
GET api/get_user{
"message": "User details retrieved",
"username": "",
"user_id": "",
"name": "",
"surname": "",
"email": "",
"labels": ""
}{
"error": "User not authenticated"
}Current authenticated user is logged out.
POST api/logout{
"message": "Logout successful"
}Follows a user. Must be authenticated.
POST api/follow/<int: user_id>{
"message": "You are now following ..."
}Unfollows a user. Must be authenticated
POST api/unfollow/<int: user_id>{
"message": "You have unfollowed ..."
}Create a post. Must be authenticated.
POST api/create-post
{
"link": "",
"image": "",
"comment": "",
"latitude": "",
"longitude": "",
}{
"message": "Post created successfully",
"post_id": ""
}{
"error": "Failed to fetch content description"
}Gets a user's posts. Must be authenticated.
GET api/get-user-posts?user_id=&page_number=&page_size={
"posts": [
{
"id": "",
"comment": "",
"image": "",
"link": "",
"created_at": "",
"total_likes": "",
"total_dislikes": "",
"tags": [""]
}
],
"current_page": "",
"total_pages": "",
"total_posts": ""
}Get specific post(s) by providing either:
- post id: Get post with ID
- post link: Get all posts for spotify link
- start date & end date: Posts between date
The last option returns paginated data and requires fields page_number and page_size to be present.
POST api/get-posts
{
"post_id": "",
}or
POST api/get-posts
{
"post_link": "",
}or
POST api/get-posts
{
"start_date": "",
"end_date": "",
"page_number": "",
"page_size": "",
}{
"id": "",
"comment": "",
"image": "",
"link": "",
"created_at": "",
"total_likes": "",
"total_dislikes": "",
"content": {
"id": "",
"link": "",
"description": "",
"content_type": ""
}
"tags": [""]
} "posts": [
{
"id": "",
"comment": "",
"image": "",
"link": "",
"created_at": "",
"total_likes": "",
"total_dislikes": "",
"content": {
"id": "",
"link": "",
"description": "",
"content_type": ""
}
"tags": [""]
}
]Likes a post. Must be authenticated.
POST api/posts/<int:post_id>/like{
"status": "success",
"message": "Post liked"
}{
"status": "success",
"message": "Post not found"
}{
"status": "success",
"message": "Post already liked"
}Dislike post. Must be authenticated.
POST api/posts/<int:post_id>/dislike{
"status": "success",
"message": "Post disliked"
}{
"status": "success",
"message": "Post not found"
}{
"status": "success",
"message": "Post already disliked"
}Most shared posts nearby the user. Must be authenticated.
GET api/most-shared-nearby-things?latitude=&longitude=&radius=&page=&size={
"songs": [
{
"id": "",
"comment": "",
"image": "",
"link": "",
"created_at": "",
"total_likes": "",
"total_dislikes": "",
"content": {
"id": "",
"link": "",
"description": "",
"content_type": ""
}
"tags": [""]
}
],
"pagination": {
"page": "",
"size": "",
"total_pages": "",
"total_songs": ""
}
}{
"error": "Invalid input for latitude, longitude, radius, page, or size."
}Saves what user plays. Must be authenticated.
POST api/save-now-playing
{
"link": "",
"latitude": "",
"longitude": ""
}{
"message": "Now playing data saved successfully.",
"id": ""
}Returns most listened songs nearby a user. Must be authenticated.
GET api/most-listened-nearby?latitude=&longitude=&radius={
"tracks": [
{
"link": "",
"description": "",
"count": ""
}
]
}Search in posts on Spot On
GET api/search?search=&page=&page_size={
"content_results_count": "",
"profile_results_count": "",
"page": "",
"page_size": "",
"contents": [
{
"id": "",
"link": "",
"description": "",
"content_type": "",
"artist_names": [""],
"playlist_name": "",
"album_name": "",
"song_name": "",
"genres": [""],
"ai_description": "",
"lyrics": ""
}
],
"profiles": [
{
"id": "",
"user_id": "",
"name": "",
"surname": "",
"labels": [""],
"username": "",
}
],
}Fetches random songs from Spotify
GET api/random-songs?limit=&genre=&q={
"songs": [
{
"link": "",
"name": "",
"artist": ""
}
],
"count": "",
}Fetch posts with AI descriptions and content suggestions
GET api/get_pages_of_spot_embeds?id=&link=&start_date=&end_date=&page=&page_size={
'id': "",
'link': "",
'content_type': "",
'artist_names': "",
'playlist_name': "",
'album_name': "",
'song_name': "",
'genres': "",
'ai_description': "",
'suggestions': [{
'name': "",
'artist': "",
'spotify_url': "",
'reason': ""
}]
}Get lyrics from database or fetch from Musixmatch if not available. Query parameters: - spotify_url: Spotify URL to lookup content and fetch lyrics - force_refresh: Optional boolean to force refresh lyrics from Musixmatch
GET api/get_lyrics?spotify_url=&force_refresh={
"lyrics": "",
"source": "",
"source_url": ""
}GET api/get_song_quiz_lyrics{
"lyric_snippet": "",
"options": [
{
"link": "",
"name": "",
"artist": ""
},
{
"link": "",
"name": "",
"artist": ""
},
{
"link": "",
"name": "",
"artist": ""
}
],
"correct_link": ""
}This endpoint allows searching for tracks, albums, or artists on Spotify using a query string.
You can optionally specify the type of content to search (track, album, artist) and the number of results.
GET api/search_spotify?q={query}&type={track,album,artist}&limit={1-50}{
"results": {
"tracks": [
{
"id": "",
"name": "",
"artists": [""],
"album": "",
"preview_url": "",
"external_url": "",
"image_url": ""
}
],
"albums": [
{
"id": "",
"name": "",
"artists": [""],
"release_date": "",
"external_url": "",
"image_url": ""
}
],
"artists": [
{
"id": "",
"name": "",
"genres": [""],
"external_url": "",
"image_url": ""
}
]
},
"query": ""
}This endpoint generates a Spotify authorization URL that the user can visit to connect their Spotify account. It does not require authentication.
GET api/spotify/auth/{
"auth_url": "string"
}This endpoint checks if the user is currently connected to Spotify.
If connected, it returns connected: true; otherwise, connected: false.
GET api/spotify/status/{
"connected": true
}This endpoint is called by Spotify after the user grants permission. It exchanges the code parameter for an access token, refresh token, and user profile information. On success, it associates the tokens with the currently authenticated user and redirects the user to a predefined frontend URL.
GET api/spotify/callback/?code={authorization_code}On success (redirects to frontend): No direct JSON response. The user is redirected to https://spotonapp.win/view-playlist?connected=true
On error:
{
"error": "string"
}