Ga naar de inhoud
cutty.dev
Voor ontwikkelaars

API en MCP-server

Maak en beheer korte links vanuit je eigen code — via de REST API of via een MCP-server in je AI-assistent.

cutty heeft een publieke API en een MCP-server. Met de eerste maak en wijzig je links vanuit code; de tweede werkt rechtstreeks vanuit een AI-assistent die het MCP-protocol spreekt. Beide gebruiken dezelfde API-sleutel.

API-sleutel

Authenticeer elke aanroep met een header:

Authorization: Bearer ck_your_key

Waar krijg je een sleutel: log in, open je dashboard → API keys → Create key. De volledige sleutel (begint met ck_) wordt maar één keer getoond, bij het aanmaken — bewaar hem meteen op een veilige plek. De limiet is 120 verzoeken per minuut per sleutel.

Base URL

Alle REST-endpoints zitten onder https://cutty.dev/api/v1. Verzoeken en antwoorden zijn JSON.

Een link aanmaken

POST /api/v1/links — de JSON-body heeft minstens een url nodig. De rest is optioneel:

  • url — bestemmingsadres (verplicht)
  • slug — eigen einde, 3–40 tekens; laat weg voor een willekeurige
  • expiresAt — vervaldatum in ISO 8601-formaat
  • maxHits — kliklimiet (1–1.000.000)
  • password — wachtwoord dat de link beschermt
  • tags — labels gescheiden door komma's om in het dashboard te ordenen
  • folder — naam van de map waar de link in komt
  • utmSource, utmMedium, utmCampaign — UTM-parameters die bij de doorverwijzing worden toegevoegd

Het antwoord geeft je slug, shortUrl en 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"}'

Lijsten en een enkele link

GET /api/v1/links geeft al je links terug. GET /api/v1/links/{slug} — details van één.

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

Bijwerken en verwijderen

PATCH /api/v1/links/{slug} werkt de velden bij die je meegeeft, DELETE /api/v1/links/{slug} verwijdert de 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 kun je onder andere instellen: targetUrl, expiresAt, maxHits, status, password, tags, folder, plus de geavanceerde velden hieronder. Een veld op null (of een lege string) wist die eigenschap.

Targeting, A/B en geavanceerde velden

Dezelfde dingen die je in de linkeditor krijgt, zijn beschikbaar via de API:

  • rules — een array met doorverwijsregels per land of apparaat, bijv. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — A/B-rotatie: een array [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; wordt gebruikt als geen enkele regel past
  • startsAt — datum (ISO 8601) waarop de link live gaat; daarvoor geeft de link 425 terug
  • webhookUrl — adres dat bij elke klik een POST-melding ontvangt (fire-and-forget)
  • serveOg met ogTitle, ogDescription, ogImageUrl — een eigen previewkaart voor social crawlers (mensen krijgen nog steeds de doorverwijzing)
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"}]}'

Bulkbewerkingen

POST /api/v1/bulk maakt veel links in één verzoek. Geef een links-array mee (elk item zoals een gewone create), tot 500 tegelijk. Het antwoord geeft een resultaat per rij terug.

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"}]}'

Linkstatistieken

GET /api/v1/links/{slug}/stats geeft een kliksamenvatting terug: het totaal, een uitsplitsing per apparaat en browser, en de verdeling over de laatste 24 uur.

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

MCP-server

Werk je met een AI-assistent, dan kun je cutty via MCP (Model Context Protocol) koppelen en hem vragen links in te korten en te ordenen, midden in het gesprek. De server draait op https://mcp.cutty.dev/mcp via Streamable HTTP, en je authenticeert met dezelfde API-sleutel — de header Authorization: Bearer ck_....

De volledige lijst met tools, kant-en-klare verbindingssnippets en voorbeelden staan op een aparte pagina: cutty MCP-server.

Werkt er iets niet?

Schrijf naar [email protected] — ik antwoord dezelfde dag.