Skip to content
Korta

URL Endpoints

Overview

Section titled “Overview”

URL endpoints are grouped under:

/api/v1/urls

There are two modes:

  1. Public shortening (no auth required)
  2. Private URL management (auth required via Bearer token or X-API-Key)

POST /urls/public

Section titled “POST /urls/public”

Create a short URL anonymously (or linked to user if authenticated).

Request body

Section titled “Request body”
{
  "originalUrl": "https://example.com/some/long/path"
}

Response

Section titled “Response”
{
  "message": "URL shortened successfully",
  "shortUrl": "https://korta.click/abc12",
  "shortId": "abc12"
}

POST /urls (protected)

Section titled “POST /urls (protected)”

Create a private short URL for the authenticated user.

Request body

Section titled “Request body”
{
  "originalUrl": "https://example.com/some/long/path",
  "shortId": "abc12"
}

Notes:

  • shortId is optional.
  • Max length for custom shortId: 5 chars.

Response

Section titled “Response”
{
  "id": 1,
  "originalUrl": "https://example.com/some/long/path",
  "shortId": "abc12",
  "clicks": 0,
  "userId": 1,
  "createdAt": "2026-02-15T10:00:00.000Z",
  "updatedAt": "2026-02-15T10:00:00.000Z"
}
Section titled “GET /urls/my-links (protected)”

Return all links for the authenticated user.

Response

Section titled “Response”
[
  {
    "id": 1,
    "originalUrl": "https://example.com",
    "shortId": "abc12",
    "clicks": 7,
    "userId": 1,
    "createdAt": "2026-02-15T10:00:00.000Z",
    "updatedAt": "2026-02-15T10:20:00.000Z"
  }
]

PATCH /urls/:shortId (protected, owner only)

Section titled “PATCH /urls/:shortId (protected, owner only)”

Update an existing short URL.

Request body

Section titled “Request body”
{
  "newShortId": "xyz99",
  "originalUrl": "https://example.com/new-target"
}

Notes:

  • At least one field is required: newShortId or originalUrl.
  • You can update one field or both in a single request.

Response

Section titled “Response”
{
  "id": 1,
  "originalUrl": "https://example.com/new-target",
  "shortId": "xyz99",
  "clicks": 7,
  "userId": 1,
  "createdAt": "2026-02-15T10:00:00.000Z",
  "updatedAt": "2026-02-15T10:30:00.000Z"
}

Validation error example (400)

Section titled “Validation error example (400)”

Empty body ({}) is rejected:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}

DELETE /urls/:shortId (protected, owner only)

Section titled “DELETE /urls/:shortId (protected, owner only)”

Delete a short URL.

Response

Section titled “Response”
{
  "message": "URL deleted successfully"
}

Redirect behavior

Section titled “Redirect behavior”
  • GET /:shortId (server root route) redirects to original URL and increments click count.
  • There is also GET /api/v1/urls/redirect/:shortId.