Skip to main content

​
Get Started with Short-URL

This quickstart guide will walk you through setting up the Short-URL API, creating your first short URL, and testing the core features. You’ll be up and running in under 5 minutes.
1

Clone and Install

Clone the repository and install dependencies.
git clone https://github.com/Tanmandal/Short-URL.git
cd Short-URL
pip install -r requirements.txt
Requirements: Python 3.11+ and MongoDB must be installed on your system.
2

Configure Environment Variables

Set up your environment variables for the API.
export MONGO_URI="mongodb://localhost:27017"
export SECRET_KEY="your-secret-key-here"
export TOKEN_EXPIRE="5"
export SURL_BASE="http://127.0.0.1:8000"
  • MONGO_URI (required): MongoDB connection string
  • SECRET_KEY (required): Secret key for JWT token signing
  • TOKEN_EXPIRE (optional): Token expiration time in minutes (default: 5)
  • SURL_BASE (required): Base URL for shortened links
  • ALLOWED_ORIGINS (optional): CORS origins (default: *)
  • URL_BLACKLIST (optional): Comma-separated list of blacklisted URL substrings
3

Start the Server

Launch the FastAPI application with Uvicorn.
uvicorn main:app --reload
Your API will be available at http://127.0.0.1:8000
FastAPI provides automatic interactive documentation at:
4

Health Check

Verify the API and database are running correctly.
curl http://127.0.0.1:8000/health

{
  "message": "Database is active"
}
5

Create Your First Short URL

Use the /create endpoint to generate a short URL.
curl -X POST "http://127.0.0.1:8000/create" \
  -H "Content-Type: application/json" \
  -d '{
    "url_code": "mylink",
    "url_pass": "secret123",
    "url": "https://example.com"
  }'

{
  "message": "URL created",
  "short_url": "http://127.0.0.1:8000/mylink"
}
6

Test the Redirect

Access your short URL to test the redirect.
curl -I http://127.0.0.1:8000/mylink
You should see a 307 redirect to https://example.com
7

Authenticate to Manage Your URL

Login to receive a JWT access token for managing your URL.
curl -X POST "http://127.0.0.1:8000/login" \
  -H "Content-Type: application/json" \
  -d '{
    "url_code": "mylink",
    "url_pass": "secret123"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
Save this token! You’ll need it for all protected endpoints.
8

Get URL Details

Use your access token to fetch statistics about your URL.
curl http://127.0.0.1:8000/details \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "message": "Details fetched successfully",
  "data": {
    "url_code": "mylink",
    "url_hits": 1,
    "url_created_at": "2026-03-04T21:30:00",
    "url_state": true,
    "url": "https://example.com"
  }
}
9

Try Management Operations

Explore other management features with your token.
Temporarily disable redirects:
curl -X PATCH http://127.0.0.1:8000/pause \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Update where the short link redirects:
curl -X PATCH "http://127.0.0.1:8000/change_url?url=https://newdomain.com" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Reset analytics to zero:
curl -X PATCH http://127.0.0.1:8000/reset_hits \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Permanently remove the short URL:
curl -X DELETE http://127.0.0.1:8000/delete \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Next Steps

Now that you have Short-URL running, explore these resources:

Authentication Guide

Deep dive into JWT authentication, token refresh, and security best practices.

API Reference

Explore all available endpoints with detailed examples and response schemas.

Deployment Guide

Learn how to deploy Short-URL to production with proper configuration.

URL Management

Learn about URL lifecycle, validation rules, and advanced features.

​
Common Issues

Ensure MongoDB is running and the MONGO_URI environment variable is correctly set.
# Check if MongoDB is running
mongosh --eval "db.adminCommand('ping')"
Access tokens expire after the time specified in TOKEN_EXPIRE (default: 5 minutes).Use the /refresh_token endpoint to get a new token without re-authenticating.
Each url_code must be unique. Choose a different code or delete the existing URL first.
URL codes must:
  • Be 3-20 characters long
  • Contain only alphanumeric characters, hyphens, and underscores
  • Not be a reserved keyword (docs, redoc, create, login, delete, pause, resume, etc.)

Build docs developers (and LLMs) love

Get started for freeTalk to us