LinkHarbor API: краткий обзор

REST API позволяет управлять LinkHarbor из ваших собственных программ: создавать страницы и ссылки, редактировать и публиковать черновики, создавать короткие ссылки или забирать статистику в свою отчётность. Эта статья для разработчиков: в ней описаны базовые правила, которые действуют для каждого эндпоинта.

#Какой путь вам подходит?

#Базовый URL и версии

Базовый URL

https://dock.at-harbor.com — все эндпоинты продукта находятся под /v1, например https://dock.at-harbor.com/v1/pages.

Версия

Сейчас есть только версия v1. Номер версии входит в путь.

Протокол

Только HTTPS.

OpenAPI

Машиночитаемое описание (OpenAPI 3.1) лежит по адресу https://dock.at-harbor.com/openapi.yaml. Его можно загрузить в Postman, Insomnia или генератор кода.

#Тестирование в песочнице

Для разработки и тестов есть отдельная песочница. Она ведёт себя как настоящий API, но полностью от него отделена: свои аккаунты, свои данные, и ничего из этого не попадает в ваше настоящее рабочее пространство.

API

https://drydock.at-harbor.com, с теми же путями, что и выше, например https://drydock.at-harbor.com/v1/pages.

Панель управления

https://sandbox-deck.linkharbor.com, например чтобы создать API-ключи.

Страницы

Опубликованные страницы появляются по адресу https://<handle>.sandbox.linkharbor.com.

Аккаунт

Ваш настоящий аккаунт LinkHarbor там не работает. Создайте отдельный аккаунт в песочнице.

Песочница не отправляет письма. Если вы регистрируетесь через API (POST /v1/auth/register), код подтверждения приходит прямо в ответе, в поле _dev_verification. То же касается сброса пароля и смены адреса электронной почты. Это поле есть только в песочнице, поэтому не полагайтесь на него в своём коде.

• Push-уведомления отключены
• Платежи проходят через тестовый режим Stripe, настоящие деньги не списываются
• Лимиты запросов составляют примерно треть от настоящих, а новых аккаунтов можно создать не больше 5 в час с одного IP-адреса
• 1-го числа каждого месяца в 3:00 UTC песочница полностью очищается, после этого все аккаунты и данные исчезают
• Каждый ответ содержит заголовок X-Environment: sandbox

#Аутентификация вкратце

1. Как владелец или админ создайте в панели управления в разделе «Callback и API» API-ключ с нужными областями доступа (начиная с Creator Pro)
2. Обменяйте ID ключа и секрет ключа на токен доступа через POST /v1/token
3. Отправляйте токен с каждым запросом в заголовке Authorization: Bearer …
4. Через 15 минут получите новый токен

Все подробности — в статье API-ключи и токены, права доступа — в статье Области доступа.

#Запросы и ответы

Формат

Запросы и ответы передаются в JSON в кодировке UTF-8. Для загрузки файлов также используется multipart/form-data.

Content-Type

Отправляйте заголовок Content-Type: application/json с каждым запросом, у которого есть тело. Любой другой тип отклоняется с 400 bad_request — в том числе тот, который curl автоматически ставит для -d, если этого заголовка нет.

Неизвестные поля

Поля, которых эндпоинт не знает, приводят к 422 validation_failed. В ответе перечислены неизвестные поля.

Некорректный JSON

Приводит к 400 invalid_json.

Размер

В зависимости от эндпоинта тело может занимать не больше 64 КБ, 1 МБ или 2 МБ, а загружаемый файл — 10 МБ. Если больше, API отвечает 413 request_too_large. Все лимиты перечислены в статье Лимиты запросов.

Списки

Возвращаются как объект с полем items, например {"items":[…]}.

Создание

Отвечает HTTP 201 и новым ID, например {"id":123}.

Действия без возвращаемого значения

Отвечают {"ok":true}.

Ошибки

Всегда имеют фиксированный формат с машиночитаемым кодом. См. Формат ошибок и коды ошибок.

#Пагинация

Единой схемы пагинации нет. Большинство списков небольшие и возвращаются целиком; параметры есть лишь у нескольких эндпоинтов:

Для sort у коротких ссылок есть значения created_desc, created_asc, redirects_desc и redirects_asc; q ищет по слагу, заголовку и целевому URL (до 100 символов, без учёта регистра). Для статистики period принимает 24h, 7d, 30d, 90d, this_month, last_month, last_30d и custom; вместо этого можно передать from и to. granularity — hour или day.

#ID запроса и язык

• Каждый ответ содержит заголовок X-Request-Id — указывайте его, когда обращаетесь в поддержку
• Если вы сами отправите заголовок X-Request-Id, API использует его
• Текст ошибки в message приходит на языке аккаунта владельца рабочего пространства, иначе следует Accept-Language; код в error всегда остаётся прежним

#Вызов из браузера?

Технически API разрешает вызовы из браузера (CORS). Но секрету ключа не место в коде, который выполняется на стороне посетителя, — ни на сайте, ни в приложении. Всегда вызывайте API со своего сервера.

#Тарифы

Квоты на число вызовов API в тарифах нет. Действуют только поминутные лимиты запросов. Лимиты контента вашего тарифа — например, на страницы, ссылки или блоки на странице — действуют через API так же, как в панели управления. См. Сравнение тарифов.

#Ваш первый запрос

# Обменять ключ на токен
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# Список страниц (scope read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

Полный пример, в котором добавляется ссылка, меняется дизайн и выполняется публикация, — в статье Обновление страницы через API.