Перейти до вмісту
cutty.dev
Для розробників

API та MCP-сервер

Створюйте та керуйте короткими посиланнями прямо з власного коду — через REST API або через MCP-сервер у вашому AI-асистенті.

cutty має публічний API та MCP-сервер. Перший дає змогу створювати й змінювати посилання з коду; другий працює просто з AI-асистента, який володіє протоколом MCP. Обидва використовують один і той самий ключ API.

Ключ API

Автентифікуйте кожен запит за допомогою заголовка:

Authorization: Bearer ck_your_key

Де взяти ключ: увійдіть, відкрийте панель → API keys → Create key. Повний ключ (починається з ck_) показується лише раз, під час створення — одразу збережіть його в надійному місці. Ліміт — 120 запитів за хвилину на ключ.

Базова URL

Усі REST-ендпоінти доступні за адресою https://cutty.dev/api/v1. Запити та відповіді — у форматі JSON.

Створення посилання

POST /api/v1/links — у тілі JSON потрібен щонайменше url. Решта — необов'язкова:

  • url — адреса призначення (обов'язково)
  • slug — власне закінчення, 3–40 символів; пропустіть, щоб отримати випадкове
  • expiresAt — дата завершення у форматі ISO 8601
  • maxHits — ліміт кліків (1–1 000 000)
  • password — пароль для захисту посилання
  • tags — мітки через кому для впорядкування в панелі
  • folder — назва теки, до якої потрапляє посилання
  • utmSource, utmMedium, utmCampaign — UTM-параметри, що додаються під час перенаправлення

У відповідь ви отримуєте slug, shortUrl і 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"}'

Список і окреме посилання

GET /api/v1/links повертає всі ваші посилання. GET /api/v1/links/{slug} — деталі одного.

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

Оновлення та видалення

PATCH /api/v1/links/{slug} оновлює передані поля, DELETE /api/v1/links/{slug} видаляє посилання.

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

Через PATCH можна задати, зокрема: targetUrl, expiresAt, maxHits, status, password, tags, folder, а також розширені поля нижче. Поле зі значенням null (або порожній рядок) очищає цю властивість.

Таргетинг, A/B та розширені поля

Те саме, що є в редакторі посилань, доступне й через API:

  • rules — масив правил перенаправлення за країною чи пристроєм, напр. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — ротація A/B: масив [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; використовується, коли жодне правило не підходить
  • startsAt — дата (ISO 8601), коли посилання стає активним; до неї посилання повертає 425
  • webhookUrl — адреса, що отримує сповіщення POST при кожному кліку (fire-and-forget)
  • serveOg разом із ogTitle, ogDescription, ogImageUrl — власна картка попереднього перегляду для ботів соцмереж (люди все одно потрапляють на перенаправлення)
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"}]}'

Масові операції

POST /api/v1/bulk створює багато посилань одним запитом. Передайте масив links (кожен елемент — як звичайне створення), до 500 за раз. У відповідь повертається результат для кожного рядка.

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

Статистика посилання

GET /api/v1/links/{slug}/stats повертає зведення кліків: загальну кількість, розбивку за пристроями та браузерами і розподіл за останні 24 години.

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

MCP-сервер

Якщо ви працюєте з AI-асистентом, можете під'єднати cutty через MCP (Model Context Protocol) і просити його скорочувати й упорядковувати посилання просто в розмові. Сервер працює за адресою https://mcp.cutty.dev/mcp через Streamable HTTP, а автентифікація — тим самим ключем API через заголовок Authorization: Bearer ck_....

Повний список інструментів, готові сніпети підключення та приклади — на окремій сторінці: MCP-сервер cutty.

Щось не працює?

Напишіть на [email protected] — відповідаю того ж дня.