API Documentation

The URLit API allows you to programmatically shorten, manage, and track URLs.

Base URL

https://urlit.zone.id/api

API Version

All endpoints are versioned with /v1. The current version is v1.

Example: https://urlit.zone.id/api/v1/shorten

✅ All API endpoints are publicly accessible – no API key required for basic shortening. For user‑specific endpoints (listing, updating, deleting), you'll need to authenticate using Firebase ID tokens.

Authentication

For endpoints that require user authentication (listing, updating, deleting URLs), you must provide a Firebase ID token in the Authorization header:

Authorization: Bearer YOUR_FIREBASE_ID_TOKEN

To obtain a Firebase ID token:

Sign in using Firebase Auth (via the web interface or your own integration).
Call currentUser.getIdToken() to get the token.
Include it in the header for authenticated requests.

                        // JavaScript example
                        const token = await firebase.auth().currentUser.getIdToken();
                        const response = await fetch('https://urlit.zone.id/api/v1/users/...', {
                          headers: { 'Authorization': `Bearer ${token}` }
                        });
                    

Shorten a URL

POST /api/v1/shorten

Create a short URL from a long URL. Optionally provide a custom slug.

Request Body

Parameter	Type	Required	Description
`url`	string	Yes	The original URL to shorten (must include http:// or https://)
`customSlug`	string	No	A custom short code (letters, numbers, hyphens only, 3-20 characters)
`userId`	string	No	Firebase UID – if provided, the URL will be associated with a user account

Response

                        {
                          "success": true,
                          "shortCode": "Ab3Kx9",
                          "shortUrl": "https://urlit.zone.id/Ab3Kx9",
                          "originalUrl": "https://example.com/very/long/url",
                          "createdAt": "2026-08-28T10:30:00.000Z"
                        }
                    

Example Request

                        curl -X POST https://urlit.zone.id/api/v1/shorten \
                          -H "Content-Type: application/json" \
                          -d '{"url": "https://example.com/very/long/url"}'
                    

Get URL Details

GET /api/v1/urls/:shortCode

Retrieve details about a specific short URL.

Parameters

Parameter	Type	Required	Description
`shortCode`	string	Yes	The short code (e.g., Ab3Kx9)

Response

                        {
                          "shortCode": "Ab3Kx9",
                          "originalUrl": "https://example.com/very/long/url",
                          "clicks": 42,
                          "status": "active",
                          "createdAt": "2026-08-28T10:30:00.000Z",
                          "createdBy": "user_uid_123"
                        }
                    

List User URLs

GET /api/v1/users/:userId/urls

Retrieve all URLs belonging to a specific user. Requires authentication (Firebase ID token).

Headers

Header	Required	Description
`Authorization`	Yes	Bearer YOUR_FIREBASE_ID_TOKEN

Response

                        {
                          "urls": [
                            {
                              "id": "Ab3Kx9",
                              "originalUrl": "https://example.com/1",
                              "clicks": 42,
                              "status": "active",
                              "createdAt": {...}
                            },
                            ...
                          ],
                          "count": 5
                        }
                    

Update a URL

PUT /api/v1/urls/:shortCode

Update the status or original URL of a short URL. Requires authentication (Firebase ID token) and ownership.

Request Body

Parameter	Type	Required	Description
`status`	string	No	`"active"` or `"disabled"`
`originalUrl`	string	No	New destination URL

Response

                        {
                          "success": true,
                          "message": "URL updated successfully"
                        }
                    

Delete a URL

DELETE /api/v1/urls/:shortCode

Permanently delete a short URL. Requires authentication (Firebase ID token) and ownership.

Response

                        {
                          "success": true,
                          "message": "URL deleted successfully"
                        }
                    

Get URL Analytics

GET /api/v1/urls/:shortCode/analytics

Retrieve click analytics for a short URL, including total clicks and recent click events.

Response

                        {
                          "shortCode": "Ab3Kx9",
                          "originalUrl": "https://example.com/long",
                          "totalClicks": 42,
                          "clicks": [
                            {
                              "timestamp": "2026-08-28T10:30:00.000Z",
                              "userAgent": "Mozilla/5.0...",
                              "referrer": "https://twitter.com",
                              "country": "US"
                            },
                            ...
                          ]
                        }
                    

Error Codes

The API uses standard HTTP status codes to indicate success or failure.

Status Code	Description
`200`	OK – request succeeded
`400`	Bad Request – missing or invalid parameters
`401`	Unauthorized – missing or invalid authentication
`403`	Forbidden – not allowed to access resource
`404`	Not Found – resource doesn't exist
`409`	Conflict – custom slug already taken
`429`	Too Many Requests – rate limiting exceeded
`500`	Internal Server Error – something went wrong

Code Examples

JavaScript (Fetch API)

                        const response = await fetch('https://urlit.zone.id/api/v1/shorten', {
                          method: 'POST',
                          headers: { 'Content-Type': 'application/json' },
                          body: JSON.stringify({
                            url: 'https://example.com/very/long/url',
                            customSlug: 'my-link'  // optional
                          })
                        });
                        const data = await response.json();
                        console.log(data.shortUrl);
                    

Python (Requests)

                        import requests

                        response = requests.post(
                            'https://urlit.zone.id/api/v1/shorten',
                            json={ 'url': 'https://example.com/very/long/url' }
                        )
                        data = response.json()
                        print(data['shortUrl'])
                    

cURL

                        curl -X POST https://urlit.zone.id/api/v1/shorten \
                          -H "Content-Type: application/json" \
                          -d '{"url": "https://example.com/very/long/url"}'
                    

Node.js (Axios)

                        const axios = require('axios');

                        const response = await axios.post('https://urlit.zone.id/api/v1/shorten', {
                          url: 'https://example.com/very/long/url'
                        });
                        console.log(response.data.shortUrl);
                    