API

API задаётся репозиторием контракта freedome_contract v1.0.0-rc.1 (закреплён в fixtures/contract/). Сервер отдаёт сами документы контракта, поэтому имена и формы не расходятся.

Транспорт	Точка входа	Источник в контракте
REST	/api/v1/*, OpenAPI /api/v1/openapi.json, Swagger UI /api/docs	openapi/mediaserver.yaml
GraphQL	/api/v1/graphql, подписки graphql-transport-ws	graphql/mediaserver.graphql
WebSocket	/api/v1/ws, подпротокол freedome.v1	asyncapi/ws.yaml
socket.io	/socket.io/, пространство имён /v1	asyncapi/socketio.yaml
OSC	UDP / TCP 7000, ответы 7001	osc/addresses.yaml, см. OSC
gRPC	Unix-сокет, TCP 50062	proto/mediaserver/…/mediaserver.proto (этот репозиторий)

Аутентификация: Authorization: Bearer <токен> — API-ключ fdk_…, локальная сессия (POST /auth/session) или облачный токен (POST /auth/token-exchange); приложения подключаются по 6-значному коду (POST /auth/pairings). Роли guest / operator / admin / superadmin — наборы scope, у каждой операции свой scope. OSC работает без токенов — по списку разрешённых сетей и роли слушателя.

Все транспорты выполняют одни и те же операции REST (operationId) с одинаковыми правами, проверками и ошибками (RFC 9457). События — одно дерево топиков (venues/{v}/players/{p}, venues/{v}/output, assets/{a}, …) с seq для возобновления (sinceSeq). Большие файлы — через tus 1.0 (/api/v1/uploads).