sink

Sink API

Sink is a link shortener running on Cloudflare. Manage links via REST API.

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer YOUR_SITE_TOKEN

Token = NUXT_SITE_TOKEN environment variable.

Base URL

https://your-sink-domain

API Reference

Create Link

POST /api/link/create
Content-Type: application/json

{
  "url": "https://example.com/long-url",
  "slug": "custom-slug",
  "comment": "optional note",
  "expiration": 1735689599,
  "apple": "https://apps.apple.com/app/id123",
  "google": "https://play.google.com/store/apps/details?id=com.example",
  "geo": {
    "US": "https://example.com/us"
  },
  "title": "Example Title",
  "description": "Example social preview description",
  "password": "optional-password",
  "redirectWithQuery": true
}

Required: url Optional: slug (auto-generated if omitted), comment, expiration (unix timestamp), apple (Apple device redirect), google (Android redirect), geo (country-specific routing map), password, unsafe, title, description, image, cloaking, redirectWithQuery

If NUXT_SAFE_BROWSING_DOH is configured and unsafe is not explicitly set, the server auto-detects via DoH and marks unsafe links automatically.

Response (201):

{
  "link": {
    "id": "abc123",
    "url": "https://example.com/long-url",
    "slug": "custom-slug",
    "createdAt": 1718119809,
    "updatedAt": 1718119809
  },
  "shortLink": "https://your-domain/custom-slug"
}

Errors: 409 (slug exists)

Query Link

GET /api/link/query?slug=custom-slug

Response (200):

{
  "id": "abc123",
  "url": "https://example.com",
  "slug": "custom-slug",
  "createdAt": 1718119809,
  "updatedAt": 1718119809
}

Errors: 404 (not found)

Edit Link

PUT /api/link/edit
Content-Type: application/json

{
  "slug": "existing-slug",
  "url": "https://new-url.com",
  "comment": "updated note"
}

Required: slug (identifies which link to edit), url Optional: other fields to update

Response (201): Same as create

Errors: 404 (not found)

Delete Link

POST /api/link/delete
Content-Type: application/json

{
  "slug": "slug-to-delete"
}

Response: 200 (empty body)

List Links

GET /api/link/list?limit=20&cursor=abc123

Parameters:

• limit: max 1024, default 20
• cursor: pagination cursor from previous response

Response:

{
  "keys": [],
  "list_complete": false,
  "cursor": "next-cursor"
}

Export Links

GET /api/link/export

Response:

{
  "version": "1.0",
  "exportedAt": "2024-01-01T00:00:00Z",
  "count": 100,
  "links": [],
  "list_complete": true
}

Import Links

POST /api/link/import
Content-Type: application/json

{
  "links": [
    {"url": "https://example1.com", "slug": "ex1"},
    {"url": "https://example2.com", "slug": "ex2"}
  ]
}

Response: imported links array

AI Slug Generation

GET /api/link/ai?url=https://example.com/article

The server can use the URL and extracted page content to generate a readable slug.

Response:

{
  "slug": "ai-generated-slug"
}

AI OpenGraph Metadata Generation

GET /api/link/og-ai?url=https://example.com/article&locale=en-US

Generates a localized OpenGraph title and description from the URL and extracted page content.

Response:

{
  "title": "Example Article",
  "description": "A concise social preview description."
}

Verify Token

GET /api/verify

Verify if the site token is valid.

Response (200):

{
  "name": "Sink",
  "url": "https://sink.cool"
}

Errors: 401 (invalid token)

Link Fields

Field	Type	Required	Description
url	string	Yes	Target URL (max 2048)
slug	string	No	Custom slug (auto-generated)
comment	string	No	Internal note
expiration	number	No	Unix timestamp
apple	string	No	iOS/macOS redirect URL
google	string	No	Android redirect URL
geo	object	No	Country-specific routing map, for example { "US": "https://example.com/us" }
title	string	No	Custom title (max 256)
description	string	No	Custom description
image	string	No	Custom image path
cloaking	boolean	No	Enable link cloaking
redirectWithQuery	boolean	No	Append query params to destination URL (overrides global NUXT_REDIRECT_WITH_QUERY)
password	string	No	Password protection for the link
unsafe	boolean	No	Mark as unsafe (shows warning page before redirect)

Analytics Endpoints

Counters

GET /api/stats/counters

Metrics

GET /api/stats/metrics

Views

GET /api/stats/views

Heatmap

GET /api/stats/heatmap

Export Access Analytics

GET /api/stats/export?startAt=1717200000&endAt=1719791999&slug=custom-slug

Returns text/csv with slug, url, viewer, views, and referer columns.

OpenAPI Docs

• JSON: /_docs/openapi.json
• Scalar UI: /_docs/scalar
• Swagger UI: /_docs/swagger

cURL Examples

Create link:

curl -X POST https://your-domain/api/link/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/example"}'

List links:

curl https://your-domain/api/link/list \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete link:

curl -X POST https://your-domain/api/link/delete \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-slug"}'