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 Quikko API is a REST API served by the Go/Echo backend. Every authenticated endpoint requires a JWT Bearer token in the Authorization header. With the exception of the short-code redirect and the CSV analytics export, every response uses a standard JSON envelope so that clients can handle success and error paths uniformly.

​
Base URL

EnvironmentURL
Developmenthttp://localhost:8080
ProductionSet the BASE_URL environment variable

​
API Prefix

All REST endpoints are mounted under /api/v1. Three special endpoints live at the server root and do not carry this prefix:
EndpointPurpose
GET /{code}Public short-URL redirect (no /api/v1 prefix)
GET /healthReadiness healthcheck — returns { "status": "ok" }
GET /wsWebSocket upgrade for real-time click events

​
Standard Response Envelope

Every JSON response wraps its payload in a consistent envelope: 
{
  "success": true,
  "data": { ... },
  "error": null,
  "meta": null
}
FieldTypeNotes
successbooleantrue on success, false on any error
dataobject | array | nullPopulated when success is true; null on error
errorobject | nullPopulated when success is false; null on success
metaobject | nullPresent only on paginated list responses; omitted otherwise

​
Error Response

When success is false, the error object contains a stable machine-readable code and a human-readable message: 
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body."
  }
}

​
Pagination

Paginated list endpoints accept the following query parameters:
ParameterDefaultMaximumDescription
page1—Page number (1-indexed)
limit20100Results per page (clamped to maximum)
When pagination applies, the meta field is included in the response alongside data: 
{
  "success": true,
  "data": [ ... ],
  "error": null,
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 134,
    "totalPages": 7
  }
}
meta.total and meta.totalPages always reflect the count after any active filters (search, isActive, etc.) have been applied.

​
HTTP Status Codes

StatusMeaning
200Success
201Resource created
400Validation error or invalid parameters
401Missing, malformed, or expired token
403Access forbidden (resource belongs to another user, or plan restriction)
404Resource not found
409Conflict (e.g. email or alias already taken)
410Gone (short URL has been deactivated)
429Rate limit exceeded
500Internal server error

​
Error Code Reference

CodeMeaning
VALIDATION_ERRORInvalid request body or query parameters
AUTH_INVALID_CREDENTIALSWrong email or password
AUTH_EMAIL_TAKENEmail already registered
AUTH_TOKEN_INVALIDMissing or malformed JWT
AUTH_TOKEN_EXPIREDJWT has expired
PLAN_LIMIT_EXCEEDEDFree plan active URL quota reached
PLAN_RANGE_NOT_ALLOWEDAnalytics time range not allowed on this plan
ALIAS_TAKENCustom alias already in use
INVALID_URLURL failed validation (bad scheme, private host, or self-referencing)
FORBIDDENResource belongs to another user
URL_NOT_FOUNDShort code does not exist
URL_INACTIVEShort URL has been deactivated
RATE_LIMIT_EXCEEDEDToo many requests — back off and retry
INTERNAL_ERRORUnexpected server error

​
Interactive Documentation

The running server exposes a Swagger UI with a built-in request builder. No additional tooling is required to explore or test any endpoint.
ResourceURL
Swagger UIGET /docs
OpenAPI spec (YAML)GET /docs/openapi.yaml
The OpenAPI spec is the authoritative source for request/response schemas. Download it from /docs/openapi.yaml to generate client SDKs with tools like openapi-generator or import it directly into Postman.

​
Explore the API

Authentication

Learn how JWT tokens are issued, refreshed, and passed on every request.

Auth Endpoints

Register, login, refresh tokens, and manage your account.

URLs

Create, list, toggle, and delete short URLs with optional custom aliases.

Analytics

Query aggregated click metrics by country, device, browser, and time bucket.

Redirect

Public redirect endpoint — resolves a short code and returns a 302 response.

WebSocket

Subscribe to real-time click events for your URLs over a persistent WebSocket connection.

Build docs developers (and LLMs) love

Get started for freeTalk to us