Skip to content

api.md

Latest commit

 

History

History
56 lines (40 loc) · 1.97 KB

api.md

File metadata and controls

56 lines (40 loc) · 1.97 KB
Raw
layout default
title API Documentation

API Documentation

The API runs locally at http://localhost:5043.

Endpoints

Method Route Authentication Purpose
GET /api/health Public Returns API health status.
GET /api/urls Clerk JWT Lists links owned by the current user.
POST /api/urls Clerk JWT Creates a short link.
GET /api/urls/{code} Clerk JWT Reads an owned link.
GET /u/{code} Public Redirects to the original URL.

Create a short link

POST /api/urls accepts JSON with an originalUrl and optional customCode.

{
  "originalUrl": "https://example.com/a/long/path",
  "customCode": "example-link"
}

Rules:

  • originalUrl must be an absolute HTTP or HTTPS URL.
  • customCode is optional.
  • A custom code must be 3 to 32 characters.
  • A custom code may contain letters, numbers, -, and _.
  • Duplicate codes return 409 Conflict.

A successful request returns 201 Created with the created short-link response.

Authentication

Private endpoints require a Clerk JWT. The API accepts the token through the standard Authorization: Bearer <token> header. It also supports X-Clerk-Session-Token, which the API converts to a bearer token for validation.

The API scopes list and individual-link operations to the authenticated user's sub claim.

Responses

  • 200 OK: successful read or health check.
  • 201 Created: short link created.
  • 401 Unauthorized: missing or invalid authentication.
  • 404 Not Found: code does not exist or is not owned by the current user.
  • 409 Conflict: requested short code already exists.
  • 422 Unprocessable Entity: URL or custom-code validation failed.

Back to documentation home