A short-link API that
tells you what happened.
REST endpoints for links, analytics, A/B variants, webhooks, and audit log. OpenAPI 3.1 spec. API keys with scopes. HMAC-signed payloads. Runs on Cloudflare's edge.
Quick start
Create your first link.
curl -X POST https://api.orphl.ink/links \
-H "Authorization: Bearer olk_<your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"destination_url": "https://example.com/spring-launch",
"title": "Spring launch",
"redirect_mode": "direct"
}' Replace <your-api-key> with a real key from your dashboard.
Core endpoints
What you can build.
The OpenAPI spec (opens in new tab) documents the whole REST API, including auth, workspaces, tags, groups, branding, cloaking rules, embeds, and proxy sessions. Below is the path most teams hit first.
| Method | Path | What it does |
|---|---|---|
| POST | /links | Create a short link with an optional custom slug, redirect mode (direct, interstitial, proxy), expiry, scheduled activation, and password. |
| GET | /links | List workspace links with filters: search, tag, group, status, health. |
| GET | /links/{linkId}/stats | Total clicks for one link over 24h, 7d, 30d or 90d (or a start/end range), with an hourly click time series. |
| PUT | /links/{linkId}/variants | Replace a link's A/B variants — weights sum to 100, per-variant click counts. |
| POST | /webhooks | Subscribe an endpoint to link events. HMAC-SHA256 signed payloads, up to 3 delivery attempts. |
| GET | /audit-log | Workspace audit trail with before/after diffs. Retention is set per workspace (default 90 days). |
| POST | /links/import | Bulk import via multipart CSV — up to 500 rows, 2 MB. Each imported link goes through moderation. |
API keys
Keys are workspace-scoped and prefixed with olk_. We store only the hash; the first eight characters (the key prefix) are kept in plain text so the dashboard can identify which key is which without ever revealing the secret. Pass the key as Authorization: Bearer olk_… on every request.
Scopes are checked per route — issue read-only keys for analytics consumers, write keys for the importer.
- links:read
- links:write
- analytics:read
- workspaces:read
- workspaces:write
- conversions:write
Webhooks
Subscribe an endpoint to the events you care about. Each delivery is a JSON POST signed with an HMAC-SHA256 of the raw body, keyed with the endpoint's signing secret (shown once at creation) and sent as X-OrphLink-Signature: sha256=<hex>; the event name is in X-OrphLink-Event. Up to 3 delivery attempts: the first, then retries after 30s and 120s. Verify the signature on receipt; reject the request if it doesn't match.
Events sent today
- · link.moderation_complete
- · link.health_failed
- · conversion.recorded
These are the only events. There are no click, creation or expiry events.
The machine-readable reference.
Every REST route, schema, and error shape in one public OpenAPI 3.1 document — import it into Postman, Insomnia, or your client generator.