Links API Endpoints

Manage short link entities within your active organization workspace.

1. Create a Short Link

POST /api/v1/links

Request Body Parameters

Field	Type	Required	Description
`url`	`string`	Yes	Destination target URL (must include `https://` or `http://`)
`slug`	`string`	No	Custom slug identifier. If omitted, a random 6-character slug is generated
`domain`	`string`	No	Target custom or system domain (defaults to `shaf.is`)
`description`	`string`	No	Human-readable title or memo
`tags`	`string[]`	No	Array of classification tags
`password`	`string`	No	Access password to gate the redirect
`expiresAt`	`string`	No	ISO 8601 UTC timestamp when the link ceases resolving
`apple`	`string`	No	Smart redirect URL for iOS visitors
`google`	`string`	No	Smart redirect URL for Android visitors

Request Example

1234567891011curl -X POST https://shaf.app/api/v1/links \
  -H "Authorization: Bearer shaf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/checkout",
    "slug": "promo-2026",
    "domain": "link.yourbrand.com",
    "tags": ["promo", "summer"],
    "apple": "https://apps.apple.com/app/id12345",
    "google": "https://play.google.com/store/apps/details?id=com.example"
  }'

2. List Links

GET /api/v1/links

Query Parameters

Parameter	Type	Default	Description
`page`	`number`	`1`	Pagination page index
`limit`	`number`	`20`	Results per page (max 100)
`search`	`string`	-	Substring search matching slug, URL, or title
`tag`	`string`	-	Filter links by specific tag
`domain`	`string`	-	Filter links by domain

3. Retrieve Link Details & Analytics

GET /api/v1/links/:slug?domain=:domain

Retrieves the link metadata along with total click impressions, unique visitors, and geographic breakdown.

4. Update a Link

PATCH /api/v1/links/:slug

Update mutable properties (destination url, description, tags, apple, google, password).

5. Delete a Link

DELETE /api/v1/links/:slug?domain=:domain

Permanently deletes the short link and invalidates edge KV caches globally.

Deleting a link is immediate and irreversible across Cloudflare's global edge network. Any traffic hitting deleted slugs will fall back to your custom 404 URL or the default Shaf 404 page.

Ask AI about this page