Документация Баунс

Публичный REST API по адресу /api/v1: аутентификация, выбор рабочего пространства, доступные пространства имён и формат ошибок.

Справочник API

Все эндпоинты с описаниями и полями; запрос можно выполнить прямо из браузера.

Спецификация OpenAPI

spec.json для генератора клиентов, Postman или вашей интеграции.

Публичный REST API Баунс живёт по адресу /api/v1. Его ключевое свойство — он не написан отдельно: и веб-приложение, и CLI, и воркеры, и этот API говорят на одном контракте. Спецификация OpenAPI генерируется из него же, поэтому документированная поверхность и достижимая поверхность совпадают по построению, а не по дисциплине.

Аутентификация

Персональный токен доступа передаётся как bearer:

Authorization: Bearer bnp_…

Токен действует от имени создавшего его сотрудника во всех рабочих пространствах, где тот состоит.

Выбор рабочего пространства

Пространство не входит в путь — его называет заголовок:

Заголовок	Значение
`x-workspace-id`	UUID рабочего пространства
`x-workspace-slug`	Код пространства из адреса, например `acme`

Достаточно одного из двух. Членство и роль токена проверяются в этом пространстве на каждом запросе. Эндпоинты, которые относятся к пользователю, а не к пространству (список пространств, ожидающие приглашения), заголовка не требуют.

Минимальный пример:

curl https://<ваш-хост>/api/v1/issues \
  -H "Authorization: Bearer bnp_…" \
  -H "x-workspace-slug: acme"

Что доступно

Поверхность v1 сгруппирована так же, как в справочнике:

Группа	Пространства имён
Работа	issues, comments, labels, projects, initiatives, teams, search
Агенты и автоматизация	agents, tasks, chat, skills, autopilots, workflows
Данные	datasets, attachments
Рабочее пространство	workspace, members, invitations, users, inbox, pins, dashboard
Интеграции	connectors, credentials
Система	health

Наружу не выходят три класса операций: вход и сессии, управление самими токенами и всё, что относится к протоколу демона — последнее закрыто на уровне предиката доступности, а не настройкой.

Соглашения

Имена полей — snake_case, отметки времени — ISO-8601 со смещением, идентификаторы — UUID.
Тела запросов — JSON. Неизвестные поля большинство эндпоинтов молча игнорирует, поэтому опечатка в имени поля не вызовет ошибку — значение просто не применится.
Списки отдаются страницами по курсору. limit по умолчанию 50, не больше 100; в ответе есть next_cursor и prev_cursor, их передают обратно в cursor за следующей или предыдущей страницей, на краях они null. offset и total в странице нет: числа отдаёт свой эндпоинт. Курсор, который сервер не выдавал, получает page_cursor_invalid; выданный под другой порядок — page_cursor_stale: прочитайте список заново с начала.
Часть эндпоинтов требует роли не ниже member, admin или owner; требование указано в описании эндпоинта.
Идентификаторы задач принимаются в человекочитаемом виде (ACME-123) там, где это указано в описании.

Ошибки

Форма ответа одна для всех ошибок, HTTP-статус ей соответствует:

{
  "defined": true,
  "code": "NOT_FOUND",
  "status": 404,
  "message": "Not Found",
  "data": { "code": "issue_not_found" }
}

code — один из BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS.
data.code — стабильная машинная причина, по которой и стоит ветвиться в коде.
message — текст для человека, он может меняться со временем.

Версионирование

Версия — в пути. Внутри v1 изменения только аддитивные: новые эндпоинты и новые необязательные поля. Ломающая ревизия вышла бы как /api/v2 со своей спецификацией, поэтому интеграция, собранная на v1, продолжает работать.

Как исследовать модель

Быстрее всего — из CLI, он читает ту же спецификацию:

bounc schema list                 # какие сущности есть
bounc schema describe issue       # операции и поля одной сущности
bounc schema search assignee      # где встречается поле

Вход и токены — как выпустить токен, которым вы будете подписывать запросы.
Справочник CLI — тот же контракт из терминала.
Задачи — основной ресурс, который читает и пишет API.

API