Go to content
cutty.dev
For developers

API and MCP server

Create and manage short links from your own code — over the REST API or through an MCP server in your AI assistant.

cutty has a public API and an MCP server. The first lets you create and change links from code; the second works straight from an AI assistant that speaks the MCP protocol. Both use the same API key.

API key

Authenticate every call with a header:

Authorization: Bearer ck_your_key

Where to get a key: sign in, open your dashboard → API keys → Create key. The full key (it starts with ck_) is shown only once, at creation — save it somewhere safe right away. The limit is 120 requests per minute per key.

Base URL

All REST endpoints live under https://cutty.dev/api/v1. Requests and responses are JSON.

Creating a link

POST /api/v1/links — the JSON body needs at least a url. The rest is optional:

  • url — destination address (required)
  • slug — custom ending, 3–40 characters; omit for a random one
  • expiresAt — expiry date in ISO 8601 format
  • maxHits — click limit (1–1,000,000)
  • password — password protecting the link
  • tags — comma-separated labels for organising in the dashboard
  • folder — name of the folder the link goes into
  • utmSource, utmMedium, utmCampaign — UTM parameters appended on redirect

The response gives you slug, shortUrl and target.

curl -X POST https://cutty.dev/api/v1/links \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/a/very/long/address","slug":"offer","tags":"campaign,summer"}'

Listing and a single link

GET /api/v1/links returns all your links. GET /api/v1/links/{slug} — details of one.

curl https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key"

Updating and deleting

PATCH /api/v1/links/{slug} updates the fields you pass, DELETE /api/v1/links/{slug} removes the link.

curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"maxHits":500}'

Via PATCH you can set, among others: targetUrl, expiresAt, maxHits, status, password, tags, folder, plus the advanced fields below. A field set to null (or an empty string) clears that property.

Targeting, A/B and advanced fields

The same things you get in the link editor are available through the API:

  • rules — an array of redirect rules by country or device, e.g. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — A/B rotation: an array [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; used when no rule matches
  • startsAt — date (ISO 8601) the link goes live; before it, the link returns 425
  • webhookUrl — address that receives a POST notification on every click (fire-and-forget)
  • serveOg with ogTitle, ogDescription, ogImageUrl — a custom preview card for social crawlers (humans still get the redirect)
curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"kind":"country","match":"DE","url":"https://example.de"}]}'

Bulk operations

POST /api/v1/bulk creates many links in one request. Pass a links array (each item like a regular create), up to 500 at a time. The response returns a result per row.

curl -X POST https://cutty.dev/api/v1/bulk \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"links":[{"url":"https://a.com"},{"url":"https://b.com","slug":"b"}]}'

Link stats

GET /api/v1/links/{slug}/stats returns a click summary: the total, a breakdown by device and browser, and the distribution over the last 24 hours.

curl https://cutty.dev/api/v1/links/offer/stats \
  -H "Authorization: Bearer ck_your_key"

MCP server

Working with an AI assistant? cutty also ships an MCP server — connect it once and manage links straight from chat. It runs at https://mcp.cutty.dev/mcp (Streamable HTTP transport), authenticated with the same ck_ key you use for the API.

The full list of ten tools (including country/device targeting and A/B tests), ready-to-paste connection snippets for Claude Code, Cursor and Claude Desktop, plus examples, live on a dedicated page: the cutty MCP server.

Something not working?

Write to [email protected] — I reply the same day.