REST API overview
How the app talks to the server in the browser, and how Pro workspaces call Linktrap from scripts.
You do not need to read this page to use Linktrap in the web UI — the dashboard and create flow call the APIs for you. Use this when you integrate from code or debug auth errors.
Base URL
All paths are relative to your deployment origin, e.g. https://your.app.
Authentication modes
| Surface | Auth | Notes |
|---|---|---|
/api/links | Clerk session cookie | Browser or same-origin fetch with credentials. |
/api/links/[id] | Clerk session | GET/PATCH/DELETE for links in your workspace. |
/api/guest/links | Guest session cookie | Public quick shorten only (quickShorten: true). Optional urlCloaking. No sign-in; guest links expire after a TTL. |
/api/links/batch | Clerk session | Bulk quick shorten; same body as guest batch. |
/api/links/quota | Clerk session | Daily link quota snapshot for the workspace. |
/api/guest/links/batch, /api/guest/links/quota | Guest session cookie | Public bulk shorten and quota (no sign-in). |
/api/generate-meta | Clerk session | OpenAI + optional Blob; costs accrue to your keys. |
/api/upload-preview-image | Clerk session | multipart/form-data field file → public Blob URL for the wizard. |
/api/stripe/checkout, portal | Clerk session | Creates Stripe URLs for the signed-in user's workspace. |
/api/stripe/webhook | Stripe signature | No Clerk; verify STRIPE_WEBHOOK_SECRET. |
/api/v1/links | Authorization: Bearer lt_… | Pro workspace API key; see below. |
/api/workspace/api-keys | Clerk session | Pro only; create/list/revoke keys. |
/api/v1/links/batch | Authorization: Bearer lt_… | Pro bulk create with API key. |
/api/workspace/custom-domains | Clerk session | Pro only; register and remove hostnames. |
Link fields (create & update)
All authenticated create/update endpoints accept the same link options:
destinationUrl— required on create (valid http/https URL).quickShorten— auto-fill safe bot preview text (no destination URL inog:description).botTitle,botDescription,ogImageUrl— custom preview for crawlers (required when not using quick shorten).humanBufferPage— countdown interstitial for humans before redirect.urlCloaking— full-page iframe so the address bar stays on the short URL.utmSource,utmMedium,utmCampaign,campaign,notes,expiresAt,isActive.
List and single-link responses include clickCount per link.
Rate limiting
POST /api/links (and v1 create) apply per-minute rate limits. Errors return 429 with a JSON error message.
Full v1 reference
Request/response shapes and examples: API v1 reference. OpenAPI: OpenAPI specification.