URLKING | Premium URL Shortener & Earn Money Online

Getting Started

1 · Pick your auth

JWT Bearer — call POST /api/login (or sign in with Google) and sendAuthorization: Bearer <token> on every dashboard API. Tokens last 30 days.

API Token — the classic shorten API GET /api takes your token as theapi query parameter. Copy it from Dashboard → Settings or rotate it withPOST /api/regenerate-key.

2 · Typical flow

Register → Login (keep the JWT) → shorten with POST /api/create → sharehttps://urlking.in/{id} → watch clicks & earnings in GET /api/stats → cash out with POST /api/withdraw/request.

Uploading files? Two steps: GET /api/dev/server tells you where to upload, then POST /api/dev/finalize registers the file and returns its share URL.

3 · Errors & limits

Errors always come as { "error": "message" } with a proper HTTP status (400 validation · 401 auth · 403 forbidden · 404 missing · 409 conflict · 429 rate-limited).

The public GET /api endpoint uses its own shape:{ status, message, shortenedUrl }. General API rate-limit applies per IP; Google auth is capped at 30 req / 15 min.

Developer API

GET/apiAPI Token

The classic public shorten API. No login required — authenticate with your API token and get a monetized short link back. Re-shortening the same URL for the same account returns the existing link (deduplicated) instead of a new one.

Error responses use the same shape: { status: "error", message: "Invalid API Token", shortenedUrl: "" }. Possible messages: "API Token is required", "URL is required", "Invalid API Token", "Account Suspended", "Alias already taken".

Query / Path Parameters

ParameterTypeRequiredDescription

apistringRequiredYour API token. Find it in Dashboard → Settings, or regenerate it via POST /api/regenerate-key.

urlstringRequiredThe long URL to shorten. If the scheme is missing, https:// is added automatically.

aliasstringOptionalCustom back-half. Must be globally unique, otherwise the API returns "Alias already taken".

bash

curl "https://go.urlking.in/api?api=YOUR_API_TOKEN&url=https://example.com/page&alias=my-deal"

json

{
  "status": "success",
  "message": "",
  "shortenedUrl": "https://go.urlking.in/api/step2/AbC12"
}

Authentication

POST/api/registerPublic

Create a new publisher account. The account is provisioned in Firebase Auth + the users table, a wallet row is created, and referral credit is applied when a valid ref is supplied.

On success the user is NOT logged in automatically — call /api/login next. Errors (400): "Username is already taken…", "Email is already registered…", validation messages.

Request Body (JSON)

ParameterTypeRequiredDescription

usernamestringRequired3–20 characters, only letters, numbers and underscores. Must be unique.

emailstringRequiredValid e-mail address, unique per account.

passwordstringRequiredMinimum 6 characters.

refstringOptionalUsername of the referrer (referral program).

bash

curl -X POST "https://go.urlking.in/api/register" \
  -H "Content-Type: application/json" \
  -d '{"username":"vikubhai","email":"[email protected]","password":"secret123","ref":"friend_username"}'

json

{
  "ok": true
}

POST/api/loginPublic

Sign in with username or e-mail + password. Returns a JWT session token valid for 30 days. Send it as Authorization: Bearer <token> on every protected call.

401 on wrong credentials, 403 if the account is suspended.

Request Body (JSON)

ParameterTypeRequiredDescription

identifierstringRequiredUsername OR registered e-mail address.

passwordstringRequiredAccount password.

bash

curl -X POST "https://go.urlking.in/api/login" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"vikubhai","password":"secret123"}'

json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
}

POST/api/google-authPublic

Sign in / auto-register with Google. Accepts either a Google ID token (credential, from GIS button) or an OAuth access token (from the custom premium button). Existing e-mail → instant login; new e-mail → account auto-created (Firebase user without password, wallet, default CPM, referral link).

Rate limit: 30 requests / 15 min / IP. Google-only signups start with has_password = 0 — the Dashboard shows the "Set Password" panel until a password is set.

Request Body (JSON)

ParameterTypeRequiredDescription

credentialstringOptionalGoogle ID token (JWT) from Google Identity Services. Verified via tokeninfo (audience + expiry).

access_tokenstringOptionalOAuth access token from the custom Google button. Verified via Google userinfo endpoint. Send at least one of the two.

refstringOptionalReferrer username, applied only when a NEW account is created.

bash

curl -X POST "https://go.urlking.in/api/google-auth" \
  -H "Content-Type: application/json" \
  -d '{"access_token":"ya29.a0AfB_…","ref":"friend_username"}'

json

{
  "token": "eyJhbGciOiJIUzI1NiIs…",
  "username": "john_doe95",
  "is_new_user": true
}

POST/api/auth/forgot-passwordPublic

Request a password-reset e-mail. A secure, expiring reset token is generated and dispatched to the registered address.

Request Body (JSON)

ParameterTypeRequiredDescription

emailstringRequiredRegistered e-mail address.

bash

curl -X POST "https://go.urlking.in/api/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

json

{
  "ok": true
}

GET/api/auth/verify-token/:tokenPublic

Check whether a password-reset token is still valid before showing the new-password form.

400 "Invalid or expired link" when the token does not exist or has expired.

Request Body (JSON)

ParameterTypeRequiredDescription

tokenstring (path)RequiredReset token received by e-mail.

bash

curl -X GET "https://go.urlking.in/api/auth/verify-token/RESET_TOKEN"

json

{
  "ok": true
}

POST/api/auth/reset-confirmPublic

Complete the password reset. Updates the Firebase password and syncs the has_password flag (so Google-only users can also use this route).

Request Body (JSON)

ParameterTypeRequiredDescription

tokenstringRequiredReset token from the e-mail link.

newPasswordstringRequiredNew password, minimum 6 characters.

bash

curl -X POST "https://go.urlking.in/api/auth/reset-confirm" \
  -H "Content-Type: application/json" \
  -d '{"token":"RESET_TOKEN","newPassword":"newSecret123"}'

json

{
  "ok": true
}

Account & Profile

GET/api/meBearer JWT

Full session profile: identity, CPM rate, API token, upload permission, payout settings and the live wallet snapshot in one call.

has_password = 0 means the account was created with Google and has no password yet — show the "Set Password" flow instead of "Change Password".

bash

curl -X GET "https://go.urlking.in/api/me" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "uid": "FirebaseUID123",
  "username": "vikubhai",
  "email": "[email protected]",
  "name": "Viku",
  "role": "user",
  "cpm": 2,
  "has_password": 1,
  "can_upload": 1,
  "api_token": "R4nd0mAp1K3y…",
  "mobile": "",
  "telegram": "",
  "youtube": "",
  "social": "",
  "referred_by": null,
  "withdrawal_method": "upi",
  "withdrawal_account": "",
  "balance": 12.5,
  "total_withdrawn": 40,
  "pending_withdrawn": 0,
  "lifetime_collected": 52.5,
  "created_at": 1700000000000
}

PUT/api/profileBearer JWT

Update profile details and payout settings in a single request. Only the fields you send are required by the client — the endpoint stores all of them.

Request Body (JSON)

ParameterTypeRequiredDescription

namestringOptionalDisplay name.

social / mobile / telegram / youtubestringOptionalContact & social fields.

withdrawal_methodstringOptional"upi" | "bank" — selects the payout rail.

withdrawal_accountstringOptionalUPI ID or masked account reference.

bank_holder / bank_name / bank_account / bank_ifscstringOptionalBank payout details (method = bank).

upi_idstringOptionalUPI ID (method = upi).

bash

curl -X POST "https://go.urlking.in/api/profile" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Viku","social":"","mobile":"+91…","telegram":"vikubhai01","youtube":"","withdrawal_method":"upi","withdrawal_account":"name@upi","upi_id":"name@upi"}'

json

{
  "ok": true
}

POST/api/change-passwordBearer JWT

Change an existing password. The old password is verified against Firebase first, then the new one is applied.

400 "No password set on your account yet…" when has_password = 0 (Google-only signup) — use /api/set-password instead.

Request Body (JSON)

ParameterTypeRequiredDescription

oldPasswordstringRequiredCurrent password.

newPasswordstringRequiredNew password, minimum 6 characters.

bash

curl -X POST "https://go.urlking.in/api/change-password" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"oldPassword":"secret123","newPassword":"newSecret123"}'

json

{
  "ok": true,
  "message": "Password updated successfully"
}

POST/api/set-passwordBearer JWT

First-time password for Google signups. No current password required (there is none). Only allowed while has_password = 0; after this the account behaves like a normal e-mail + password account.

400 "Password already set…" when a password already exists.

Request Body (JSON)

ParameterTypeRequiredDescription

newPasswordstringRequiredPassword to set, minimum 6 characters.

bash

curl -X POST "https://go.urlking.in/api/set-password" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"newPassword":"mySecret123"}'

json

{
  "ok": true,
  "message": "Password set successfully"
}

POST/api/regenerate-keyBearer JWT

Rotate the API token used by the public Developer API. The old token stops working immediately.

bash

curl -X POST "https://go.urlking.in/api/regenerate-key" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "api_key": "NEW_R4nd0mAp1K3y…"
}

Link Management

POST/api/createBearer JWT

Create a short link. Without an alias and expiry, re-submitting the same destination URL returns the existing link id (dedupe). With an alias you choose the back-half.

Share as {SHORT_DOMAIN}/{id} — e.g. https://urlking.in/xK9mP. Requests with an alias skip dedupe on purpose.

Request Body (JSON)

ParameterTypeRequiredDescription

urlstringRequiredDestination URL. https:// is added automatically when the scheme is missing.

aliasstringOptionalCustom back-half, globally unique → 409 "Alias taken" otherwise.

expires_atstring (date)OptionalISO timestamp after which the link dies (410 Gone on redirect).

bash

curl -X POST "https://go.urlking.in/api/create" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/very/long/target","alias":"my-deal","expires_at":"2026-12-31T18:30:00.000Z"}'

json

{
  "id": "xK9mP"
}

GET/api/history?page=1Bearer JWT

Paged short-link history for the logged-in account (5 per page, newest first). Deleted links and internal file rows (raw_*) are excluded.

Query / Path Parameters

ParameterTypeRequiredDescription

pagenumberOptionalPage number, default 1.

bash

curl "https://go.urlking.in/api/history?page=1?page=1"

json

[
  {
    "id": "xK9mP",
    "url": "https://example.com/page",
    "created_at": 1700000000000,
    "expires_at": null
  },
  {
    "id": "aB3zQ",
    "url": "https://example.com/other",
    "created_at": 1699999000000,
    "expires_at": 1730000000000
  }
]

PUT/api/linkBearer JWT

Change the destination URL of an existing short link. Redirect caches are invalidated instantly.

Only your own links can be updated (uid is enforced server-side).

Request Body (JSON)

ParameterTypeRequiredDescription

idstringRequiredShort-link id to update.

urlstringRequiredNew destination URL.

bash

curl -X POST "https://go.urlking.in/api/link" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"xK9mP","url":"https://new-destination.com"}'

json

{
  "ok": true
}

POST/api/mass-createBearer JWT

Bulk shorten up to 20 URLs in one request. Each URL gets a fresh random id.

400 "Maximum 20 URLs allowed at once" above the limit.

Request Body (JSON)

ParameterTypeRequiredDescription

urlsstring[]RequiredArray of URLs, max 20 per request, schemes auto-completed.

bash

curl -X POST "https://go.urlking.in/api/mass-create" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://site-one.com","site-two.com/page"]}'

json

{
  "shortLinks": [
    "https://urlking.in/mQ2xZ",
    "https://urlking.in/Lp0wN"
  ]
}

Stats & Wallet

GET/api/statsBearer JWT

Dashboard analytics aggregate: click counts and earnings for the account. Admins can throttle heavy polling via an hourly-limit switch (429 when triggered).

bash

curl -X GET "https://go.urlking.in/api/stats" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "today_clicks": 320,
  "yesterday_clicks": 512,
  "total_clicks": 15420,
  "today_earnings": 0.64,
  "total_earnings": 52.5
}

GET/api/stats/earningsBearer JWT

Earnings time-series used by the dashboard chart (daily buckets).

bash

curl -X GET "https://go.urlking.in/api/stats/earnings" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "daily": [
    {
      "date": "2026-11-04",
      "earnings": 0.64,
      "clicks": 320
    }
  ]
}

GET/api/stats/devicesBearer JWT

Traffic split by device / platform for the account.

bash

curl -X GET "https://go.urlking.in/api/stats/devices" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "devices": [
    {
      "name": "Android",
      "share": 62.4
    },
    {
      "name": "Windows",
      "share": 24.1
    },
    {
      "name": "iOS",
      "share": 13.5
    }
  ]
}

GET/api/user/top-linksBearer JWT

Best performing short links ranked by clicks.

bash

curl -X GET "https://go.urlking.in/api/user/top-links" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "links": [
    {
      "id": "xK9mP",
      "url": "https://example.com",
      "clicks": 8421,
      "earnings": 32.1
    }
  ]
}

GET/api/wallet/balanceBearer JWT

Lightweight live wallet balance (briefly cached per user for speed).

bash

curl -X GET "https://go.urlking.in/api/wallet/balance" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "balance": "12.5000",
  "currency": "USD"
}

File Uploader

GET/api/dev/server?size=&name=&type=JWT + Upload Access

Step 1 of every upload — asks the backend where to send the bytes. ≤100 MB goes to the Telegram pipeline; larger files get a presigned Cloudflare R2 URL (quota checked); duplicates of known hashes can return an instant clone.

Max file size 3 GB. 403 "Access denied." when the account lacks upload permission; 403 "Storage Limit Reached!…" when the large-file quota would be exceeded.

Query / Path Parameters

ParameterTypeRequiredDescription

sizenumberOptionalFile size in bytes (drives the routing decision).

namestringOptionalFile name (used for the quota ledger and defaults).

typestringOptionalMIME type.

bash

curl "https://go.urlking.in/api/dev/server?size=&name=&type=?size=5242880&name=movie.mp4&type=video/mp4"

json

{
  "upload_type": "r2",
  "url": "https://r2-presigned-upload-url…",
  "file_code": "Fc8xK2aQ",
  "r2_key": "uploads/…"
}

POST/api/dev/finalizeJWT + Upload Access

Step 2 — register the uploaded bytes as a file link. Creates the internal raw_ row and the public file_xxx row and returns the shareable download-page URL.

Request Body (JSON)

ParameterTypeRequiredDescription

file_codestringRequiredCode returned by /api/dev/server.

file_namestringOptionalDisplay name of the file.

file_sizestring|numberOptionalSize in bytes (formatted server-side to "5.00 MB" style).

upload_typestringOptional"r2" | "telegram" | "clone" (as returned by /server).

r2_keystringOptionalR2 object key (upload_type = r2).

file_hashstringOptionalHash for dedupe/clone detection.

bash

curl -X POST "https://go.urlking.in/api/dev/finalize" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_code":"Fc8xK2aQ","file_name":"movie.mp4","file_size":"5242880","upload_type":"r2","r2_key":"uploads/…","file_hash":"sha256…"}'

json

{
  "short_id": "file_Ab12Cd34",
  "url": "https://go.urlking.in/d?id=raw_Xy9…",
  "file_name": "movie.mp4",
  "file_size": "5.00 MB"
}

GET/api/dev/storage-infoJWT + Upload Access

Storage meter data — counts ONLY active files (soft-deleted / orphan rows are excluded), so the number always matches the File Manager list.

bash

curl -X GET "https://go.urlking.in/api/dev/storage-info" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "used": "728.31 MB",
  "limit": "20 GB",
  "files": 42
}

GET/api/dev/my-filesJWT + Upload Access

File Manager listing: every active file owned by the account with its share URL, name and formatted size.

bash

curl -X GET "https://go.urlking.in/api/dev/my-files" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "files": [
    {
      "id": "file_Ab12Cd34",
      "file_name": "movie.mp4",
      "file_size": "5.00 MB",
      "url": "https://go.urlking.in/d?id=raw_Xy9…",
      "created_at": 1700000000000
    }
  ]
}

DELETE/api/dev/delete-file/:idJWT + Upload Access

Soft-delete a file: it disappears from the File Manager and its size is freed from the storage meter.

Request Body (JSON)

ParameterTypeRequiredDescription

idstring (path)RequiredPublic file id (file_xxx…).

bash

curl -X DELETE "https://go.urlking.in/api/dev/delete-file/file_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "ok": true
}

PUT/api/dev/rename-fileJWT + Upload Access

Rename a file in the File Manager (also syncs the name on the storage backend).

404 "File not found or unauthorized" for other users’ files.

Request Body (JSON)

ParameterTypeRequiredDescription

short_idstringRequiredPublic file id.

new_namestringRequiredNew display name.

bash

curl -X POST "https://go.urlking.in/api/dev/rename-file" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"short_id":"file_Ab12Cd34","new_name":"My Holiday Video.mp4"}'

json

{
  "ok": true
}

GET/api/dev/all-permissionsJWT + Upload Access

Upload permission overview used by the manager panel (who can upload, global allow-all flag).

bash

curl -X GET "https://go.urlking.in/api/dev/all-permissions" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "can_upload": 1,
  "allow_all": 0
}

Downloads

POST/api/download/infoPublic

Public file metadata for the download page header — resolves both raw_ internal ids and public file_ ids.

Request Body (JSON)

ParameterTypeRequiredDescription

file_idstringRequiredraw_xxx or file_xxx id from the file link.

bash

curl -X POST "https://go.urlking.in/api/download/info" \
  -H "Content-Type: application/json" \
  -d '{"file_id":"raw_Xy9AbC"}'

json

{
  "filename": "movie.mp4",
  "size": "5.00 MB"
}

POST/api/download/generate-tokenPublic

Issue the final download token/URL for a file. Monetization gate: a valid click on the short link within the last 24 hours is required.

403 { error: "Session Expired", redirect: "https://go.urlking.in/{publicId}" } when no valid click exists — the client should follow redirect to the short link first.

Request Body (JSON)

ParameterTypeRequiredDescription

file_idstringRequiredraw_xxx or file_xxx id.

bash

curl -X POST "https://go.urlking.in/api/download/generate-token" \
  -H "Content-Type: application/json" \
  -d '{"file_id":"raw_Xy9AbC"}'

json

{
  "token": "dl_xxx…",
  "url": "https://cdn…/file?token=dl_xxx"
}

Withdrawals & Referrals

GET/api/withdraw/info?page=1Bearer JWT

Withdrawal center data: balances, the minimum limit for the user’s selected method, and paged transaction history (withdrawals + rewards combined).

Query / Path Parameters

ParameterTypeRequiredDescription

pagenumberOptionalHistory page (3 entries per page).

bash

curl "https://go.urlking.in/api/withdraw/info?page=1?page=1"

json

{
  "balance": "12.5000",
  "total_withdrawn": "40.0000",
  "pending_withdrawn": "0.0000",
  "min_limit": 5,
  "history": [
    {
      "id": "W123",
      "amount": 10,
      "status": "approved",
      "method": "upi",
      "created_at": 1700000000000,
      "transaction_type": "withdrawal"
    }
  ],
  "total": 4,
  "pages": 2,
  "currentPage": 1
}

POST/api/withdraw/requestBearer JWT

Create a withdrawal request from the available wallet balance. Amount must respect the method’s minimum limit; the request goes to the admin queue.

Request Body (JSON)

ParameterTypeRequiredDescription

amountnumberRequiredAmount in USD to withdraw.

bash

curl -X POST "https://go.urlking.in/api/withdraw/request" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount":10}'

json

{
  "ok": true,
  "message": "Withdrawal request submitted"
}

GET/api/referral/statsBearer JWT

Referral program dashboard: referred users, lifetime commission and the shareable referral link.

bash

curl -X GET "https://go.urlking.in/api/referral/stats" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

json

{
  "total_earnings": 3.2,
  "referral_count": 7,
  "referral_link": "https://urlking.in/register?ref=vikubhai",
  "commission_rate": "5%",
  "users": [
    {
      "username": "friend_one",
      "created_at": 1700000000000
    }
  ]
}

System

GET/healthPublic

Container-level liveness probe (used by uptime monitors and orchestrators).

bash

curl -X GET "https://go.urlking.in/health"

json

{
  "status": "ok"
}

GET/api/server-healthPublic

Deeper health check with process uptime and a live database latency measurement.

bash

curl -X GET "https://go.urlking.in/api/server-health"

json

{
  "status": "Online 🟢",
  "uptime": "132.45 mins",
  "db_latency": "3ms"
}

GET/api/maintenance-statusPublic

Returns the current maintenance flag so clients can show/hide the maintenance screen.

bash

curl -X GET "https://go.urlking.in/api/maintenance-status"

json

{
  "maintenance": false,
  "message": ""
}