Skip to main content

​
Overview

sptfy.in uses PocketBase for authentication and API access. All authenticated endpoints require a valid PocketBase auth token.

​
Authentication Methods

​
OAuth2 (GitHub)

The primary authentication method is GitHub OAuth2. 
const pb = new PocketBase('https://your-instance.com');

// Initiate OAuth2 flow
const authData = await pb.collection('users').authWithOAuth2({
  provider: 'github'
});

console.log(authData.token); // JWT token
console.log(authData.record); // User record

​
Using Auth Tokens

Once authenticated, include the token in subsequent requests: 
curl -X GET "https://api.sptfy.in/api/links" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

​
Turnstile Token (Bot Protection)

For unauthenticated link creation, you must include a Cloudflare Turnstile token to prevent abuse.
​
X-Turnstile-Token
string
required
Cloudflare Turnstile challenge token obtained from the client-side widget

​
Getting a Turnstile Token

1

Add Turnstile Widget

Include the Turnstile widget in your HTML:
<div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
2

Get Token from Callback

Retrieve the token from the Turnstile callback:
window.onloadTurnstileCallback = function () {
  turnstile.render('.cf-turnstile', {
    sitekey: 'YOUR_SITE_KEY',
    callback: function(token) {
      // Use this token in X-Turnstile-Token header
      console.log(token);
    }
  });
};
3

Include in API Request

Pass the token in the X-Turnstile-Token header when creating links

​
Example with Turnstile

const turnstileToken = '...'; // From Turnstile widget callback

const response = await fetch('https://api.sptfy.in/api/links', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Turnstile-Token': turnstileToken
  },
  body: JSON.stringify({
    from: 'https://open.spotify.com/track/...'
  })
});

​
User Information

​
Get Current User

curl -X GET "https://api.sptfy.in/api/me" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
Response
​
user
object | null
User object if authenticated, null otherwise

​
Update User Profile

Update username and onboarding status. 
curl -X PATCH "https://api.sptfy.in/api/me" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newusername"
  }'
Request Body
​
username
string
New username (3-150 chars, alphanumeric, dots, hyphens, underscores)
Response
​
user
object
Updated user record
Error Responses
​
401
error
Not authenticated
​
400
error
Invalid username format
​
409
error
Username already taken

​
PocketBase Collections

sptfy.in uses these PocketBase collections:

random_short

Main collection for shortened links. Write operations require authentication or Turnstile token.

viewList

Read-only view of links with user information. Used for fetching user’s links.

analytics

Analytics data for link visits (country, user agent, timestamps)

users

User accounts managed by PocketBase auth

​
Error Handling

All endpoints return standard HTTP status codes:
Status CodeMeaning
200Success
201Created
204No Content (successful deletion)
400Bad Request (invalid parameters)
401Unauthorized (missing or invalid auth token)
403Forbidden (not owner of resource)
404Not Found
409Conflict (duplicate slug)
503Service Unavailable (maintenance mode)
Error Response Format 
{
  "message": "Error description"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us