> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Модуль API

Версионируемый публичный контракт, механика ключей и поверхность OpenAPI.

## Прежде чем начать

Откройте загруженный проект supastack в Visual Studio Code, используя «Файл» → «Открыть папку», затем выберите «Терминал» → «Новый терминал». Корень репозитория — это папка, содержащая package.json, приложения и пакеты. Запустите команду ниже и оставьте терминал открытым. Если команда не распознается, завершите руководство по установке инструмента, прежде чем продолжить.

Сначала прочтите руководство по платформе. Сервер — это процесс приложения, который отвечает на запросы браузера или телефона. Веб читает apps/web/.env.local, Expo читает apps/mobile/.env.local, а команды миграции базы данных читают корневой .env. Демонстрация без базы данных / панели мониторинга отделена от реальных учетных записей / аутентификации, для которых необходимо перенести Postgres. Для оформления заказа только на телефоне или компьютере требуется отдельно работающий веб-сервер.

[Установите инструменты и получите код](https://supastack.dev/ru/docs/web/before-you-start.md)

[Изучение команд, файлов и конфигурации](https://supastack.dev/ru/docs/web/terminal-basics.md)

[Пройдите руководство по первому запуску в Интернете](https://supastack.dev/ru/docs/web/ship-in-5-minutes.md)

```
corepack pnpm --filter @supastack/web dev
```


## Настройка и конфигурация

packages/api — источник истины для публичной REST-поверхности: zod-схемы запросов, ответов и обёртки ошибок плюс документ OpenAPI (openApiDocument), отдаваемый на /api/v1/openapi. Обработчики маршрутов компонуют эти схемы вместо переопределения форм.

API-ключи выпускаются по пространствам с префиксом sk_<env>_, хранятся хэшированными со сравнением за постоянное время и несут scope — по умолчанию read. api-keys.ts владеет созданием, поиском и отзывом.

```
apiV1 = "/api/v1"

schemas: currentWorkspace, entitlement,
  modelRequirements, createAiTaskRequest,
  aiTask, aiTaskResult, apiError

openApiDocument → GET /api/v1/openapi
```


## Рабочий процесс внедрения

Добавляйте эндпоинты внутри существующей версии: расширяйте схемы, сохраняйте обёртку ошибок и регенерируйте поверхность OpenAPI, чтобы /api/docs оставался точным. Ломающие изменения получают новую версию, а не тихое изменение формы.

Разрешайте пространство вызывающего из предъявленного ключа, применяйте те же правила энтайтлмента и валидации, что и веб-приложение, и ограничивайте частоту по ключу.


## Проверка и устранение неполадок

Контрактно тестируйте каждую форму маршрута против схем пакета. Проверьте, что неизвестные, отозванные и недостаточно-scoped запросы все завершаются задокументированной обёрткой ошибки, и что документ OpenAPI остаётся валидным JSON.


## Вперёд

[Ограничение частоты](https://supastack.dev/ru/docs/modules/rate-limiting.md)