API Reference
Create Link
POST /api/v1/links — Create a new short link.
POST /api/v1/links
Create a new short link. If no custom slug is provided, one is auto-generated (5 characters).
Request
curl -X POST https://trak.sh/api/v1/links \
-H "Authorization: Bearer trak_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/my-long-url",
"customSlug": "my-link",
"tag": "marketing"
}'Body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Yes | The destination URL. Must be a valid HTTP/HTTPS URL. |
customSlug | string | No | Custom slug (3-30 chars, lowercase letters, numbers, hyphens). If omitted, auto-generated. |
tag | string | No | Optional tag for categorization (e.g., "marketing", "social", "blog"). |
Response (201 Created)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"slug": "my-link",
"shortUrl": "https://trak.sh/my-link",
"destinationUrl": "https://example.com/my-long-url",
"tag": "marketing",
"createdAt": "2026-04-03T12:00:00.000Z"
}Errors
| Status | Error | Cause |
|---|---|---|
| 400 | "Invalid request body" | Missing url field or invalid URL format |
| 400 | "Custom slugs must be 3-30 characters..." | Invalid slug format |
| 400 | "This slug is reserved" | Slug matches a reserved word (api, admin, docs, etc.) |
| 409 | "This slug is already taken" | Another link already uses this slug |
Notes
- Pro users can create slugs as short as 3 characters
- Links created via API never expire (Pro perk)
- OG metadata (title, description, image) is fetched automatically in the background
- Auto-generated slugs contain at least one digit to avoid dictionary word collisions