Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Andr21Da16/Quikko/llms.txt

Use this file to discover all available pages before exploring further.

The URLs API is the core of Quikko. Use it to create short links (with auto-generated or custom short codes), list and filter your URLs with pagination, activate or deactivate links, and delete them. All endpoints require authentication via Authorization: Bearer <accessToken>.
The Free plan enforces a limit on the number of active URLs. Creating a URL or re-activating a deactivated one both count against this quota. Deactivating a URL frees up a slot immediately.

​
POST /api/v1/urls

POST /api/v1/urls Creates a new short URL. If no customAlias is supplied, Quikko auto-generates a random short code. Rate limited per authenticated user (RATE_LIMIT_CREATE_PER_MIN). URL validation is applied before any database write. The originalUrl must:
  • Use the http or https scheme
  • Not resolve to a private or loopback IP (e.g. 192.168.x.x, 127.0.0.1, 10.x.x.x)
  • Not be a self-referential URL pointing back to the Quikko service itself

​
Request body

​
originalUrl
string
required
The destination URL. Must be a valid http or https URI.
​
customAlias
string
Optional custom short code. Alphanumeric, 3–30 characters. If omitted, a random code is generated. Returns 409 ALIAS_TAKEN if already in use.

​
Response — 201 Created

Returns a full URLResponse object. See the URLResponse fields section below.

​
Error codes

HTTPCodeWhen
400VALIDATION_ERRORMissing originalUrl or malformed body
400INVALID_URLURL fails scheme/private-IP/self-referential check
401AUTH_TOKEN_INVALIDMissing or invalid Bearer token
403PLAN_LIMIT_EXCEEDEDFree plan active-URL quota reached
409ALIAS_TAKENRequested customAlias is already in use
429RATE_LIMIT_EXCEEDEDToo many creation requests from this user
# Create a URL with auto-generated short code
curl -s -X POST http://localhost:8080/api/v1/urls \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"originalUrl": "https://example.com/very/long/path?ref=campaign"}'

# Create a URL with a custom alias
curl -s -X POST http://localhost:8080/api/v1/urls \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"originalUrl": "https://example.com/product-launch", "customAlias": "launch-2025"}'

​
GET /api/v1/urls

GET /api/v1/urls Lists the authenticated user’s short URLs with pagination, optional text search, and status filtering. Filters are resolved in the database — meta.total and meta.totalPages reflect the already-filtered count.

​
Query parameters

​
page
integer
Page number. Defaults to 1.
​
limit
integer
Results per page. Defaults to 20, maximum 100 (clamped automatically).
​
search
string
Case-insensitive partial match against shortCode or originalUrl. Treated as a literal string (no regex).
​
isActive
boolean
Filter by active state. true returns only active URLs, false returns only inactive. Omit to return all. Values other than true/false return 400 VALIDATION_ERROR.

​
Response — 200 OK

Returns an array of URLResponse objects plus a pagination meta block.
​
data
URLResponse[]
Paginated array of URL records. See URLResponse fields.
​
meta
object
Pagination metadata.
# List all URLs, second page
curl -s "http://localhost:8080/api/v1/urls?page=2&limit=10" \
  -H "Authorization: Bearer <access-token>"

# Search for a specific URL with active filter
curl -s "http://localhost:8080/api/v1/urls?search=launch&isActive=true" \
  -H "Authorization: Bearer <access-token>"

​
GET /api/v1/urls/check-alias

GET /api/v1/urls/check-alias Checks whether a custom alias is available before creating a URL. Use this in form validation to give users real-time feedback without triggering a full URL creation.

​
Query parameters

​
alias
string
required
The alias to check. Returns 400 VALIDATION_ERROR if omitted.

​
Response — 200 OK

​
alias
string
The alias that was checked, echoed back.
​
available
boolean
true if the alias is free to use, false if it is already taken.
curl -s "http://localhost:8080/api/v1/urls/check-alias?alias=my-link" \
  -H "Authorization: Bearer <access-token>"
# {"success":true,"data":{"alias":"my-link","available":true},"error":null}

​
GET /api/v1/urls/code/

GET /api/v1/urls/code/{shortCode} Returns the full metadata and QR code for a single URL owned by the authenticated user. Feeds the URL detail screen in the Quikko dashboard.
A URL that belongs to another user or does not exist returns 403 FORBIDDEN — Quikko intentionally does not distinguish between “not found” and “not yours” to avoid leaking short code existence.

​
Path parameters

​
shortCode
string
required
The short code of the URL to retrieve (e.g. xYz12A).

​
Response — 200 OK

Returns a full URLResponse object including the base64-encoded QR code. See URLResponse fields. 
curl -s http://localhost:8080/api/v1/urls/code/xYz12A \
  -H "Authorization: Bearer <access-token>"

​
PATCH /api/v1/urls//active

PATCH /api/v1/urls/{id}/active Activates or deactivates a short URL. The Redis redirect cache is kept in sync automatically.
  • Deactivating a URL frees up one slot in the Free plan quota.
  • Re-activating a URL consumes one slot and may return 403 PLAN_LIMIT_EXCEEDED if the quota is full.

​
Path parameters

​
id
string
required
The MongoDB ObjectID hex string of the URL.

​
Request body

​
isActive
boolean
required
true to activate, false to deactivate.

​
Response — 200 OK

Returns the standard envelope with data: null.

​
Error codes

HTTPCodeWhen
400VALIDATION_ERRORMissing or malformed isActive field
401AUTH_TOKEN_INVALIDMissing or invalid Bearer token
403FORBIDDENURL belongs to another user or does not exist
403PLAN_LIMIT_EXCEEDEDFree plan quota reached when attempting to re-activate
# Deactivate a URL
curl -s -X PATCH http://localhost:8080/api/v1/urls/64f1a2b3c4d5e6f7a8b9c0d1/active \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"isActive": false}'

​
DELETE /api/v1/urls/

DELETE /api/v1/urls/{id} Permanently deletes a short URL, removes it from MongoDB, and purges its entry from the Redis redirect cache. This action cannot be undone.

​
Path parameters

​
id
string
required
The MongoDB ObjectID hex string of the URL to delete.

​
Response — 200 OK

Returns the standard envelope with data: null.

​
Error codes

HTTPCodeWhen
401AUTH_TOKEN_INVALIDMissing or invalid Bearer token
403FORBIDDENURL belongs to another user or does not exist
curl -s -X DELETE http://localhost:8080/api/v1/urls/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer <access-token>"

​
URLResponse fields

The URLResponse object is returned by POST /api/v1/urls, GET /api/v1/urls, and GET /api/v1/urls/code/{shortCode}.
​
id
string
MongoDB ObjectID hex string — use this as the {id} path parameter for PATCH and DELETE requests.
​
shortCode
string
The short code portion of the URL, e.g. xYz12A or a custom alias like launch-2025.
​
shortUrl
string
The fully qualified short URL, e.g. http://localhost:8080/xYz12A. This is the link you share.
​
originalUrl
string
The destination URL the short link redirects to.
​
isCustomAlias
boolean
true if a custom alias was specified at creation time, false for auto-generated codes.
​
isActive
boolean
Whether the URL currently accepts redirects. Inactive URLs redirect visitors to a branded error page.
​
createdAt
string
ISO 8601 creation timestamp.
​
totalClicks
integer
Approximate total click count. Incremented via a fire-and-forget counter for low-latency redirects. For precise time-series click data use the Analytics API.
​
qrCodeBase64
string
The QR code for shortUrl as a PNG data URI (data:image/png;base64,...). Generated on demand, not persisted. Returns an empty string if QR generation failed.

Build docs developers (and LLMs) love

Get started for freeTalk to us