Огляд API

fibe.gg API — це RESTful JSON API, що надає програмний доступ до всіх ресурсів платформи. Використовуйте його для автоматизації створення середовищ, інтеграції з CI/CD пайплайнами або побудови власних інструментів.

Базовий URL:

https://fibe.gg/api

Автентифікація

API підтримує два методи автентифікації:

Bearer Token (API-ключ)

Рекомендований метод для програмного доступу. Додайте ваш API-ключ у заголовок Authorization:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://fibe.gg/api/playrooms

На основі сесії

Якщо ви вже авторизовані у веб-інтерфейсі, API приймає ваш cookie сесії. Це корисно переважно для дослідження API через браузер.

API-ключі

Генерація ключів

Ви можете згенерувати API-ключі з:

• Веб-інтерфейсу — Перейдіть до профілю → API Keys
• API — POST /api/keys

Кожен ключ включає:

Поле	Опис
Label	Зрозуміла назва для ключа
Client ID	Публічний ідентифікатор у форматі pk_live_*
Token	Секретний токен (показується тільки один раз при створенні)
Scopes	Дозволи, надані цьому ключу
Expires At	Необовʼязкова дата закінчення

Безпека токену

API-токен показується тільки один раз при створенні ключа. Зберігайте його надійно. Якщо втрачено, видаліть ключ та створіть новий.

Скоупи

Кожен API-ключ має один або кілька скоупів, що контролюють до яких ресурсів та дій він має доступ:

Скоуп	Опис
playrooms:read	Перегляд Playroom
playrooms:write	Створення та оновлення Playroom
playrooms:delete	Видалення Playroom
playrooms:manage	Повне керування Playroom (включає read, write, delete + операції з SSH-ключами)
playzones:read	Перегляд Playzone
playzones:write	Створення, оновлення, підключення та синхронізація Playzone
playzones:delete	Видалення Playzone
playspecs:read	Перегляд Playspec
playspecs:write	Створення та оновлення Playspec (включаючи монтовані файли та облікові дані реєстрів)
playspecs:delete	Видалення Playspec
playgrounds:read	Перегляд Playground (включаючи логи, compose, метадані змінних)
playgrounds:write	Створення, пересоздання та продовження Playground
playgrounds:delete	Знищення Playground
import_templates:read	Перегляд імпорт-шаблонів
import_templates:write	Створення та оновлення імпорт-шаблонів
launch:write	Використання Launch ендпоінту
keys:manage	Створення та видалення API-ключів

Термін дії ключів

Ключі можуть мати необовʼязкову дату закінчення. Прострочені ключі автоматично відхиляються. Ключі без дати закінчення залишаються дійсними до явного видалення.

Обробка помилок

Всі відповіді з помилками мають однаковий формат:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Validation failed",
    "details": {
      "name": ["can't be blank"]
    }
  }
}

Коди помилок

HTTP-статус	Код помилки	Опис
400	BAD_REQUEST	Відсутні або невалідні параметри
401	UNAUTHORIZED	Необхідна автентифікація або вона не вдалася
403	FORBIDDEN	Недостатньо дозволів або порушення скоупу
404	RESOURCE_NOT_FOUND	Запитаний ресурс не існує
409	CONFLICT	Конфлікт стану ресурсу (напр., видалення Playroom з активними Playground)
422	VALIDATION_FAILED	Тіло запиту не пройшло валідацію
422	LOCKED	Ресурс заблокований і не може бути змінений
422	INVALID_STATE	Операція не валідна для поточного стану ресурсу
422	QUOTA_EXCEEDED	Досягнуто ліміт ресурсів акаунту

Тестування у браузері

Оскільки API підтримує автентифікацію на основі сесії, ви можете тестувати ендпоінти прямо у браузері, будучи авторизованим. Просто перейдіть за URL API, наприклад:

https://fibe.gg/api/playrooms

Відповідь буде у форматі JSON. Використовуйте інструменти розробника браузера або утиліту jq для форматування.

Пагінація

Поточний API повертає повні набори результатів без пагінації. Для великих колекцій фільтруйте результати за допомогою параметрів запиту конкретних ендпоінтів.