Skip to main content

​
Quickstart Guide

This guide will walk you through setting up the TrackGeek API locally and making your first authenticated request.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (v18 or higher)
  • Docker and Docker Compose
  • Git
  • PostgreSQL (via Docker)
  • Redis (via Docker)

​
Installation

1

Clone the repository

git clone https://github.com/TrackGeek/api.git
cd api
2

Install dependencies

npm install
3

Set up environment variables

Copy the example environment file and configure it:
cp .env.example .env
Update the .env file with your configuration:
.env
# SERVER
PORT=40287

# DATABASE
DATABASE_URL='postgresql://user:password@localhost:5432/trackgeek'

# CACHE
REDIS_URL='redis://localhost:6379'

# AUTH
BETTER_AUTH_URL='http://localhost:40287'
BETTER_AUTH_SECRET='your-secret-key-here'
WEB_URL='http://localhost:5173'

# Social Providers (Optional - configure only what you need)
GOOGLE_CLIENT_ID=''
GOOGLE_CLIENT_SECRET=''
DISCORD_CLIENT_ID=''
DISCORD_CLIENT_SECRET=''
GITHUB_CLIENT_ID=''
GITHUB_CLIENT_SECRET=''

# EMAIL
RESEND_API_KEY=''
RESEND_FROM=''

# INTEGRATIONS
IMGBB_API_KEY=''
HARDCOVER_API_KEY=''
TMDB_API_KEY=''
IGDB_CLIENT_ID=''
IGDB_CLIENT_SECRET=''
Generate a secure random string for BETTER_AUTH_SECRET using: openssl rand -base64 32
4

Start Docker containers

Start PostgreSQL and Redis:
docker compose up -d
5

Run database migrations

Set up the database schema:
npm run prisma:migrate
npm run prisma:generate
6

Start the development server

npm run dev
You should see:
Server is running on http://localhost:40287
API documentation available at http://localhost:40287/docs

​
Your First Request

Now that the API is running, let’s make some requests!

​
Search for Anime (Public Endpoint)

Some endpoints don’t require authentication. Let’s search for anime: 
curl http://localhost:40287/anime/search?q=naruto

​
Create an Account

To access protected endpoints, you need to authenticate. Let’s create an account: 
curl -X POST http://localhost:40287/auth/sign-up/email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123",
    "name": "John Doe"
  }'
The sign-up endpoint automatically creates a user profile with a generated username. Session cookies are set automatically for subsequent requests.

​
Sign In

If you already have an account, sign in to get your session: 
curl -X POST http://localhost:40287/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123"
  }'

​
Make an Authenticated Request

Now that you’re authenticated, let’s update your profile: 
curl -X PATCH http://localhost:40287/profile \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "bio": "Anime enthusiast and gamer",
    "timezone": "America/New_York"
  }'

​
Get Anime Details

Fetch detailed information about a specific anime: 
curl http://localhost:40287/anime/details/1535

​
Response Format

All successful responses return JSON with a consistent structure:
Success Response
{
  "anime": {
    "id": 1535,
    "title": "Death Note",
    "synopsis": "...",
    "status": "finished_airing",
    "episodes": 37
  }
}
Errors follow a standardized format:
Error Response
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Authentication required"
}

​
Interactive API Documentation

TrackGeek provides interactive API documentation powered by Swagger/Scalar. Visit the docs to explore all endpoints: 
http://localhost:40287/docs
The interactive documentation is only available in development mode (NODE_ENV=development).

​
Common Response Codes

CodeMeaningDescription
200OKRequest succeeded
201CreatedResource created successfully
204No ContentRequest succeeded with no response body
400Bad RequestInvalid request parameters
401UnauthorizedAuthentication required
403ForbiddenInsufficient permissions
404Not FoundResource not found
422Unprocessable EntityValidation failed
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error

​
Next Steps

Authentication

Learn about social providers, magic links, and bearer tokens

API Reference

Explore all available endpoints and their parameters

Media Tracking

Learn how to track anime, games, movies, and more

Social Features

Discover followers, comments, reactions, and feed events
Remember to never commit your .env file or expose your BETTER_AUTH_SECRET in public repositories.

Build docs developers (and LLMs) love

Get started for freeTalk to us