Overview
The Vinyl Catalog API provides a RESTful interface for managing vinyl records, tracks, and user profiles. The API is built on Cloudflare Workers with full observability including structured logging and automatic tracing.
Authentication
Most endpoints require JWT authentication. Obtain a token by logging in with your credentials.
Rate Limiting
The API is currently running on Cloudflare Workers free tier with inherent rate limiting at the platform level.
Response Format
All responses are in JSON format with appropriate HTTP status codes.
System Endpoints
Health & Monitoring
GET
/api/v1/health
Health check endpoint with database and storage connectivity verification.
Public
GET
/api/v1/metrics
API metrics including vinyl count, track count, and storage statistics.
Public
Authentication
Login
POST
/api/v1/auth/login
Authenticate user and return JWT token for subsequent requests.
Public
Vinyls
Vinyl Operations
GET
/api/v1/vinyls
Retrieve a list of all vinyl records in the catalog.
Auth Required
POST
/api/v1/vinyls
Create a new vinyl record in the catalog.
Auth Required
GET
/api/v1/vinyls/:id
Retrieve a specific vinyl record by its unique identifier.
Auth Required
PUT
/api/v1/vinyls/:id
Update an existing vinyl record.
Auth Required
DELETE
/api/v1/vinyls/:id
Delete a vinyl record from the catalog.
Auth Required
POST
/api/v1/vinyls/:id/favorite
Toggle the favorite status of a vinyl record.
Auth Required
Tracks
Track Operations
GET
/api/v1/vinyls/:id/tracks
Retrieve all tracks associated with a specific vinyl record.
Auth Required
POST
/api/v1/vinyls/:id/tracks
Add a new track to a vinyl record.
Auth Required
PUT
/api/v1/vinyls/:id/tracks/:track_id
Update an existing track within a vinyl record.
Auth Required
DELETE
/api/v1/vinyls/:id/tracks/:track_id
Remove a track from a vinyl record.
Auth Required
Profile
Profile Operations
GET
/api/v1/profile
Retrieve the public profile information.
Public
PUT
/api/v1/profile
Update the user profile information.
Auth Required
POST
/api/v1/profile/photo
Upload a profile photo for the user account.
Auth Required
Uploads
File Operations
POST
/api/v1/vinyls/:id/cover
Upload a cover image for a vinyl record.
Auth Required
GET
/uploads/:filename
Serve uploaded files from R2 storage.
Public