NERVA API — документация

Быстрый старт — 5 минут

1. Войдите в NERVA и оформите Pro (API — только на платном тарифе).
2. Настройки → API-доступ → создайте ключ nrv_… (показывается один раз).
3. Добавьте агентов в слоты: кнопка «Агенты» → Слоты (до 5).
4. Скопируйте пример справа и выполните первый запрос.

curl -X POST https://<ваш-домен>/api/v1/agents/run \
  -H "Authorization: Bearer nrv_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"slot": 2, "task": "Найди баги в этом коде: …"}'

import requests

r = requests.post(
    "https://<ваш-домен>/api/v1/agents/run",
    headers={"Authorization": "Bearer nrv_ваш_ключ"},
    json={"slot": 2, "task": "Найди баги в этом коде: …"},
    timeout=120,
)
result = r.json()["results"]["2"]
print(result["response"])   # полный ответ
print(result["tokens"])     # потрачено токенов

const res = await fetch("/api/v1/agents/run", {
  method: "POST",
  headers: {
    Authorization: "Bearer nrv_ваш_ключ",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ tasks: { 0: "выжимка новости", 2: "ревью кода" } }),
});
const { results } = await res.json();   // параллельный запуск

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

• • Ключ создаётся в веб-интерфейсе: Настройки → API-доступ. До 5 активных ключей на аккаунт.
• • Передаётся в каждом запросе: Authorization: Bearer nrv_…
• • Полный ключ показывается один раз — потом только маска. Утёк ключ? Отзовите и создайте новый.
• • Истечение подписки Pro гасит все ключи (403 key_expired) до продления.
• • Один ключ = один аккаунт. Передача третьим лицам запрещена офертой.

POST /api/v1/chat

OpenAI-совместимый чат. Тело: { message } или { messages: [...] }, опционально conversationId для продолжения диалога из веба.

{
  "id": "chatcmpl-nerva-…",
  "object": "chat.completion",
  "model": "nerva-1.3",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "…" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 210, "completion_tokens": 358, "total_tokens": 568 },
  "nerva": { "conversationId": "…", "trust": 0.87, "stages": ["…"] }
}

GET /api/v1/agents

Дашборд агентов: слоты, статусы, токены, счёт месяца и состояние пула серверов. Клиент вставил ключ в свой код — агенты из веб-интерфейса появляются здесь.

{
  "slots": [
    { "slot": 0, "presetId": "deepseek_coder", "name": "DeepSeek Coder", "emoji": "💻",
      "status": "idle", "tokensUsed": 9123, "costRub": 182.46 },
    { "slot": 2, "presetId": "google_gemini", "name": "Google Gemini", "status": "stopped", … }
  ],
  "freeSlots": [1, 3, 4],
  "totalTokens": 14680,
  "monthlyBill": { "period": "2025-11", "totalTokens": 14680, "amountDue": 293.6, "tokenRate": 0.02 },
  "server": { "capacity": 3, "running": 0, "loadPercent": 0, "health": "GREEN" }
}

POST /api/v1/agents/run

Запуск задачи на агенте. Ответ полный, без стриминга. Один агент — { slot, task }, параллельно — { tasks: { slot: task, … } } (до 5 слотов).

{ "slot": 2, "task": "string — задача, до 8000 символов" }
{ "tasks": { "0": "…", "4": "…" } }   // параллельный запуск

{
  "results": {
    "2": { "ok": true, "slot": 2, "preset": "DeepSeek Coder",
           "response": "Найдено 3 потенциальных бага…",
           "tokens": 1523, "costRub": 30.46, "tokensTotal": 10646 }
  }
}

{
  "results": { "4": { "ok": false, "poolFull": true,
                      "error": "Все серверы заняты (3/3). Докупите ёмкость за 300 ₽" } },
  "error": { "message": "…", "type": "pool_full" }
}

Модели данных

Slot (агент в слоте):
  slot:        int 0..4            — номер слота (слотов ровно 5)
  presetId:    string              — "google_gemini" | "microsoft_copilot" | "deepseek"
                                     | "deepseek_coder" | "nerva_researcher" | "nerva_writer"
  status:      "idle" | "running" | "stopped" | "error"
  tokensUsed:  int                 — токены за текущий месяц (real-time)
  costRub:     float               — tokensUsed × tokenRate

ServerPool:
  base:        3                   — базовые серверы (1 сервер = 1 одновременная задача)
  addons:      int                 — докупленные ёмкости (по 300 ₽)
  capacity:    base + addons
  running:     int                 — задач в полёте
  health:      "GREEN" <60% | "YELLOW" <85% | "RED" ≥85%

MonthlyBill:
  period:      "YYYY-MM"
  totalTokens: int                 — включая токены удалённых (корзина) агентов
  amountDue:   float               — к оплате в конце месяца
  tokenRate:   0.02                — ₽ за токен

Биллинг и лимиты

• • Тариф: 0,02 ₽ за токен (вход + выход — итоговое число потраченного).
• • Постоплата: счёт за фактический расход выставляется в конце месяца; в течение месяца видна накопленная оценка.
• • Токены агента, удалённого через корзину, не сгорают — идут в финальный счёт.
• • Слотов ровно 5. Базовая ёмкость пула — 3 одновременные задачи; доп. сервер — 300 ₽ (СБП, кнопка «Докупить сервер» в разделе «Серверы»).
• • Дневная квота сообщений общая для веб-чата, /api/v1/chat и запусков агентов (один аккаунт — один бюджет).
• • Rate limit: 30 запросов/мин на ключ (429 + Retry-After).

Коды ошибок

Webhooks

Планируется (v1.1): события agent.completed, pool.full, bill.ready на ваш URL с подписью HMAC. Следите за changelog.

Changelog

Юридическое

• • Платформа — посредник (прокси) между клиентом и моделью; ответственность за ответы моделей несёт провайдер.
• • Права на сгенерированный контент принадлежат клиенту; права на сам API — платформе.
• • API-ключ — доступ к аккаунту: передача третьим лицам запрещена; при утечке отзовите ключ в настройках.
• • Обработка персональных данных — по 152-ФЗ; согласие фиксируется при регистрации. Логи запросов хранятся ограниченный срок.