Create and manage short links

Antics Links turns an HTTP or HTTPS destination into a stable public URL of the form https://sh.turtletech.us/{slug}. Links created in Antics, OokCite, and Ridley keep separate ownership, allowances, and usage totals even when they belong to the same TurtleTech account.

Create a link in the dashboard

Open Dashboard > Links, enter a destination, and select Create link. The default is a generated ten-character slug, a temporary 302 redirect, query forwarding, and immediate activation. Account owners can request a custom slug containing 3–64 ASCII letters, digits, hyphens, or underscores.

Optional controls include:

• a title and tags for dashboard organization;

• a start and end time in RFC 3339 format;

• a lifetime visit limit;

• 301, 302, 307, or 308 redirect status; and

• query-string forwarding.

The destination must be an absolute HTTP or HTTPS URL. Antics rejects embedded credentials, control characters, destinations on the public short-link host (to prevent redirect loops), and hosts on the destination reputation blocklist (destination_blocked). Operators extend the list with ANTICS_LINK_BLOCKED_HOSTS. A periodic sweep disables stored links whose destination later matches.

Machines file a link with folder_path (OokCite/Collections, Blog/pdf/2024). Humans send folder_id or create folders at POST /api/link-folders. GET /api/link-folders returns one-hop lifetime cards. GET /api/link-folders/{id}/stats is period visits only and never unique people. id=ungrouped is the unfiled set. period=12mo is 400. The dashboard set pane loads that route.

Create a link through the API

Use an account API key and a stable Idempotency-Key for retries:

curl -X POST https://antics-api.turtletech.us/api/links \
  -H "Authorization: Bearer $ANTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: article-42" \
  -d '{
    "target_url": "https://example.com/articles/42",
    "title": "Article 42",
    "status_code": 302,
    "forward_query": true,
    "tags": ["articles"],
    "folder_path": "OokCite/Collections"
  }'

The first successful request returns 201 Created. An identical retry returns 200 OK with the original link. Reusing the same key for different link properties returns 409 Conflict. The optional JSON source_id is equivalent to Idempotency-Key; when both are sent, their values must match. folder_id is filing, not remint identity: a retry never moves an existing row. Send folder_path to create-or-get exclusive link folders (Blog/pdf/2024). That path is not a site folder and has no Kanidm group. GET /api/links?folder= returns the titled rows in one folder. GET /api/link-folders returns flat folder cards with lifetime visits, last_visit_at, link_count, and active_link_count only.

Do not send an app_id. Antics derives it from the authenticated caller, so one application cannot create links against another application’s allowance.

Redirect lifecycle

GET counts a visit; HEAD does not. Every redirect response, missing-link response, and gone-link response carries Cache-Control: no-store.

• An unknown slug returns 404 Not Found.

• A disabled, expired, not-yet-valid, or exhausted link returns 410 Gone.

• Deleting a link or rotating its slug permanently tombstones the old slug, so it also returns 410 Gone and is never reassigned.

• Incoming query parameters are appended to the destination when query forwarding is enabled.

Destinations and status codes remain editable for 302 and 307 links. The destination and status of 301 and 308 links are immutable; rotate or replace a link when a permanent redirect needs a different destination.

Roles and visibility

Viewers can list links and read private statistics. Editors can create links, update links, and enable or disable them. Owners can also choose custom slugs, rotate slugs, and delete links. An Antics account owner can view all application link groups for the account; source applications can access only their own. Unauthorized cross-application lookups return 404 Not Found rather than revealing that a link exists.

Usage and privacy

Active-link limits are enforced independently for each application when a link is created or re-enabled. Monthly redirect usage is metered and reported but does not break established redirects. A plan downgrade leaves existing links available while preventing creation or re-enabling beyond the new allowance.

Private statistics include visits, daily unique-visitor buckets, human and bot counts, time series, referrer hosts, countries, and device classes. The daily bucket is an XXH3-64 pseudonym derived from the date, link, user agent, and source address. Raw source addresses and full referrer URLs are not stored in link analytics.