API Reference

FairLinks API.

Pay-per-link REST API. Auth with a Bearer token. Every link creation goes through the Fair quality gate — failed creates are voided, never billed.

Base URL

https://api.faircompany.ai/v1/links

Authentication

All requests use a Bearer token. Get one from fairlinks.ai/app.

Authorization: Bearer fair_live_...

Pricing

$0.006 per link created. Click serving is unmetered. The cost is held against your wallet at create time, settled on success, voided on failure.

Endpoints

POST/v1/links

Create a short link.

{
  "url": "https://yourcompany.com/landing?utm=x",
  "slug": "launch",
  "domain": "links.yourcompany.com"
}

Returns the created link with a hold_id:

{
  "id": "lnk_01HX...",
  "short_url": "https://links.yourcompany.com/launch",
  "url": "https://yourcompany.com/landing?utm=x",
  "status": "active",
  "hold_id": "hold_01HX...",
  "estimated_cost_usd": "0.006"
}

GET/v1/links/:id

Fetch a link by ID. Returns full state including settled cost.

DELETE/v1/links/:id

Permanently delete a link. The short URL stops resolving.

POST/v1/links/:id/archive

Archive (hide from dashboard but keep redirecting). Use /v1/links/:id/unarchive to restore.

POST/v1/links/batch

Create up to 1,000 links in one call. Each link is independently held + settled. Failed creates are voided.

GET/v1/links/:id/analytics

Per-link analytics: total clicks, unique visitors, top countries, top referrers, device breakdown.

GET/v1/links/domains

List custom domains in your workspace. Each domain has a verification status and auto-renewing TLS.

GET/v1/links/:id/qr

Render a QR code PNG for the link. Use /v1/links/:id/qr/styled for branded colors / logo.

Errors

  • 402 Payment Required — wallet balance below the hold amount. Top up at fairlinks.ai/app.
  • 401 Unauthorized — missing or invalid Bearer token.
  • 409 Conflict — slug already taken on this domain.
  • 422 Unprocessable — invalid destination URL.
  • 429 Rate Limit — exponential backoff with the Retry-After header.

SDKs

Typed clients available for TypeScript / Python via @fair/sdk (npm) and fair-sdk (PyPI). Full OpenAPI spec at api.faircompany.ai/openapi.