Быстрый старт API

Этот быстрый старт проверяет, что бэкенд может аутентифицироваться и читать ваш аккаунт. Вам нужен активный платный тариф, терминал с curl и доступ к Панель → Настройки → Разработчик.

Текущий API v1 управляет и синхронизирует ресурсы. Это не транспорт пользовательского чата: конечные точки диалогов и заявок только для чтения.

1. Создайте ключ с минимальными правами#

Создайте ключ с именем Local API quickstart, выберите account:read и sites:read и выберите короткий срок. Скопируйте ключ в открытом виде немедленно; он не будет показан снова.

Не используйте ключ провайдера от OpenAI, Anthropic, Gemini, Deepgram или ElevenLabs. Публичный API требует ключ Make Agent Fast, начинающийся с maf_live_.

2. Сохраните его для этого терминала#

export MAF_API_KEY="maf_live_..."

Подтвердите, что переменная существует, не печатая секрет:

test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"

Не коммитьте ключ в .env, примеры истории shell, тестовые фикстуры или браузерный бандл. Для развёрнутого кода используйте менеджер секретов хоста.

3. Изучите аккаунт#

curl --fail-with-body --include https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Ожидаемый статус: 200 OK. Тело содержит data.id, информацию тарифа и прав и сводку кошелька. Ответ также содержит x-request-id; сохраняйте это значение при сообщении о неудачном запросе.

{
  "data": {
    "id": "ACCOUNT_ID",
    "email": "owner@example.com",
    "plan": { "id": "pro", "status": "active" },
    "entitlements": { "site_limit": 3, "live_voice": true },
    "wallet": { "balance": 151 }
  }
}

Поля могут добавляться без изменения пути /v1. Игнорируйте неизвестные поля вместо отклонения ответа.

4. Перечислите сайты#

curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Ответы коллекций используют эту оболочку:

{
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Если has_more истинно, отправьте точное значение next_cursor как параметр запроса cursor следующего запроса. Не декодируйте и не конструируйте курсоры.

5. Обработайте структурированную ошибку#

Временно уберите заголовок Authorization и повторите /me. Ответ должен быть 401 со стабильным кодом:

{
  "error": {
    "code": "authentication_required",
    "message": "Provide an API key in the Authorization bearer header.",
    "request_id": "6c0b2f2e-..."
  }
}

Продакшен-код должен ветвиться на error.code, а не сравнивать message. Логируйте операцию, HTTP статус и ID запроса без логирования ключа.

6. Сделайте первую запись безопасно#

Создайте отдельный ключ, который также имеет sites:write, agents:write и knowledge:write; не расширяйте ключ чтения быстрого старта. Следуйте Рецептам API, чтобы создать сайт, добавить обоснованные знания и опубликовать его с явными ключами идемпотентности.

Частые сбои первого запроса#

Продолжите с Областями и ошибками, Справочником API и Лимитами частоты.