Быстрый старт
Войдите, создайте тестовый проект и ключ только с нужными областями, вызовите GET /v1/tools, настройте один сервис, а после приёмочного тестирования создайте отдельный live-ключ.
export GALON_API_BASE="https://api.galon.ai"
export GALON_API_KEY="gln_test_..."
curl "$GALON_API_BASE/v1/tools" -H "Authorization: Bearer $GALON_API_KEY"
Аутентификация и изоляция
Передавайте API-ключ в заголовке Authorization: Bearer. Каждый ключ привязан к одному арендатору, проекту и окружению. Храните его только в серверном хранилище секретов, никогда в браузере, мобильном приложении или репозитории.
Ключи с ограничением по сервисам
Выдавайте точные области, например mail:send, domain:lookup или build:create. Используйте отдельный ключ для каждого приложения. Избегайте шаблонов сервиса, если интеграции не нужны все операции, и сразу отзывайте неиспользуемые ключи.
mail:send
domain:lookup
domain:read
build:create
build:read
artifact:read
job:read
Асинхронные задания и идемпотентность
Изменения возвращают задание. Передавайте стабильный Idempotency-Key: одинаковый ключ и намерение возвращают то же задание, а тот же ключ с другим намерением — HTTP 409. Проверяйте состояние задания и повторяйте только безопасные или идемпотентные запросы.
POST /v1/jobs
GET /v1/jobs/{job_id}
POST /v1/jobs/{job_id}/cancel
GET /v1/builds/{job_id}/artifacts
Отправка писем
POST /v1/emails принимает from_email, subject, text или html, а также to: один адрес или список. cc и bcc — необязательные списки; вместе to, cc и bcc содержат не более 50 разных получателей, и каждый получатель учитывается в вашей квоте и в оплачиваемом использовании. Каждый получатель получает собственную копию со своей ссылкой отписки в один клик, поэтому получатели bcc никогда не раскрываются; заблокированные получатели (отказы, жалобы, отписки) пропускаются. attachments — список не более чем из 10 объектов с filename, content (base64) и необязательным content_type; закодированное письмо должно быть меньше 25 МБ, исполняемые файлы отклоняются. scheduled_at (ISO 8601 с часовым поясом, не более чем на 72 часа вперёд) откладывает отправку; POST /v1/emails/{job_id}/cancel отменяет её, пока она в очереди. POST /v1/emails/batch принимает {"emails": [...]} с 1–100 сообщениями без вложений; каждое сообщение становится отдельным job, идемпотентным по Idempotency-Key пакета и своей позиции. to_email по-прежнему принимается для одного получателя. Атомарна только регистрация пакета (atomic=true); выполнение и доставка независимы. Повтор требует точно тот же упорядоченный список; любое изменение содержимого, размера или порядка возвращает HTTP 409.
POST /v1/emails
POST /v1/emails/batch
POST /v1/emails/{job_id}/cancel
Ошибки
HTTP 401 означает недействительные или истёкшие данные, 403 — недостаточную область, 409 — конфликт идемпотентности или версии, 422 — неверный запрос, 503 — временную недоступность.
Машиночитаемая справка
Используйте контракт OpenAPI для схем и руководство интеграции LLM для инструкций агентам. Канонический язык — английский; пути, поля, области и примеры одинаковы во всех переводах.