REST API

Base URL: https://linkmag.net/v1. The OpenAPI document at https://linkmag.net/v1/openapi.json is the machine-readable contract; GET /v1 lists the same endpoints.

Formats

Authentication

Requests send Authorization: Bearer <key>. Keys start with lm_. Signed-in users create and revoke keys on the API keys page; without a browser session, the device flow issues one:

curl -s -X POST https://linkmag.net/v1/keys/requests \
  -H 'Content-Type: application/json' -d '{"client_name": "My agent"}'

The response holds user_code, approve_url, request_id and device_code. The user opens the link, signs in and approves the code. Meanwhile the claim endpoint is polled every interval seconds:

curl -s -X POST https://linkmag.net/v1/keys/requests/REQUEST_ID/claim \
  -H 'Content-Type: application/json' -d '{"device_code": "DEVICE_CODE"}'

It answers 202 {"status":"pending"} until approval, then 200 with api_key, exactly once. Requests expire after 15 minutes.

Endpoints

Checkout and portal links are for the user to open; plan rules are in Pricing.

Errors

Errors carry a machine code, a message and a fix:

{"error": {"code": "unauthorized", "message": "This call needs an API key.", "fix": "Request one with POST /v1/keys/requests, …"}}

The card endpoint answers 403 for a verified domain past the plan's domain limit. Past the fair-use limit of 20,000 new cards per site per UTC day, it redirects (302) to the page's own og:image, or answers 503 with Retry-After when the page has none; cached cards keep serving.

Short links

• Destination: a page on one of the site's served domains (the verified domains its plan covers). Any other URL is refused with forbidden. A destination the site already links to returns the existing link.
• Limit: 10,000 links per site. Deleting a site deletes its links.
• People get a 302 to the page and are counted.
• Crawlers for link previews and search (X, LinkedIn, Slack, Discord, iMessage, Google, Bing and others) get the page's title and description with the site's card as the image, and are not counted. The card is drawn and cached like any other. Other automated visits may be counted.
• Older links created before sites existed no longer redirect: ones made without an account are retired (404), and ones made from an account open a page that shows the destination with a button to continue. New links always belong to a site.

Custom short domain

On Business, PUT /v1/sites/{siteId}/short-domain serves the site's links on a subdomain of a served domain, such as go.example.com. The response names a CNAME record for the user to add, plus a TXT record when Vercel asks for one. The domain activates once the records resolve; GET on the same path re-checks it, and pending domains are re-checked every hour for 7 days.

If the site leaves Business, or the parent domain stops being served, the short domain stops serving and is removed within the hour. Links shared on it stop working; the same links keep working on the LinkMagnet URL.