Публичного API у VOIR AI нет — продукт не запущен, и ни один
сервер не отвечает на api.voir.su. Зато у нас есть спроектированный
API-контур: ресурсы, методы, формат ошибок, модель авторизации и лимиты. Мы
публикуем его как целевую архитектуру —
чтобы партнёр заранее видел, какой интерфейс получит, и мог проверить наши
обещания на вменяемость. Интерактивной «песочницы», которая притворяется живой,
на этой странице не будет: фальшивый 200 OK в консоли обманывает
сильнее, чем честное «реализовано 0 из 12».
12 эндпоинтов · целевая архитектура песочницы нет · сознательно
На день публикации этой страницы положение дел такое:
api.voir.su не обслуживает запросы, выдачи ключей не существует.voir_sk_…) недействительны, идентификаторы вымышлены.Зачем тогда эта страница? Потому что API-контур спроектирован: мы знаем, какие ресурсы появятся, какие методы им нужны и как будут выглядеть ошибки. Показать контракт заранее — способ уважать время того, кто планирует интеграцию. Это та же логика честности, что и в тарифах: мы не продаём то, чего нет.
Структурные числа страницы: 12 эндпоинтов в плане, 3 группы ресурсов, 3 фазы дорожной карты, 0 реализованных эндпоинтов.
Эндпоинты-план Целевая архитектура
Контур повторяет то, что продукт делает в интерфейсе: принять задачу, разобрать её на подзадачи, назначить отделам, вернуть результат. Поэтому и ресурсы те же — задачи, запуски агентов и команд, вебхуки для событий и служебный профиль аккаунта. Ниже — полный план первого публичного релиза: путь, метод, назначение и то, что эндпоинт вернёт. Вызвать нельзя ни один.
Программный аналог делегирования через AI CEO: текст задачи, приоритет, дедлайн и необязательные ограничения по отделам. Система принимает задачу в разбор и возвращает её идентификатор.
Постраничная выдача задач аккаунта с фильтрами по состоянию (принята, разобрана, в работе, завершена) и по отделу-исполнителю. Курсорная пагинация, как в примерах ниже.
Полное состояние одной задачи: подзадачи после разбора AI CEO, назначенные отделы, текущие статусы исполнения и итоговый результат, когда он сведён.
Уточнить приоритет, дедлайн или формулировку, пока задача в разборе. Изменение задачи, уже назначенной отделам, создаёт новую ревизию разбора — старая сохраняется в истории.
Список AI-агентов, доступных аккаунту по тарифу: роль, отдел, навыки и текущая загрузка. Тот же каталог, что виден в интерфейсе платформы.
Точечный запуск одного агента с инструкцией и входными данными, минуя общий разбор задачи. Для интеграций, которым нужен конкретный исполнитель — например, только квалификация лида агентом продаж.
Состояние одного запуска: очередь, исполнение, результат или ошибка с машиночитаемым кодом. Длинные запуски опрашиваются этим эндпоинтом либо приходят вебхуком.
Передача задачи сразу команде — группе агентов с маршрутизацией внутри. Команда сама распределяет подзадачи между участниками; для вызывающего это один ресурс, а не оркестрация руками.
Регистрация URL и набора событий (задача разобрана, запуск завершён, результат сведён). Каждое уведомление подписывается HMAC-ключом подписки: получатель проверяет подпись и не верит на слово — тот же принцип, что в живом контуре ЮKassa.
Все активные подписки аккаунта с их событиями и состоянием доставки. Недоставленные события хранятся и повторяются с экспоненциальной задержкой — повторная доставка видна в списке.
Отключение подписки: события на URL больше не отправляются, история доставок сохраняется в аккаунте для разбора. Операция идемпотентна — повторный DELETE вернёт тот же успех.
Кто владеет ключом: аккаунт, тариф, доступные отделы и текущее потребление лимитов — запросы за окно, активные запуски, очередь. Служебный эндпоинт для самодиагностики интеграции.
Анатомия Демонстрация · статичный текст
Оба блока ниже — статичный текст, а не живая консоль: браузер ничего никуда не отправляет, идентификаторы и ключи вымышлены. Мы показываем форму контракта — структуру запроса, формат успеха и формат ошибки, — чтобы интеграцию можно было проектировать уже сейчас, не дожидаясь запуска.
POST /v1/tasks HTTP/1.1
Host: api.voir.su
Authorization: Bearer voir_sk_test_0000000000
Content-Type: application/json
Idempotency-Key: 7c1e0a42-b8f3
{
"title": "Разобрать кассовый разрыв за октябрь",
"priority": "high",
"deadline": "2026-11-10T18:00:00Z",
"departments": ["finance", "sales"],
"context": "Выручка есть, на счёте минус — нужен разбор."
}HTTP/1.1 201 Created
Content-Type: application/json
{
"object": "task",
"id": "task_9f2c41de",
"state": "accepted",
"title": "Разобрать кассовый разрыв за октябрь",
"priority": "high",
"departments": ["finance", "sales"],
"created_at": "2026-11-03T09:00:00Z",
"decomposition": null
}HTTP/1.1 422 Unprocessable Entity
{
"error": {
"type": "validation_error",
"code": "department_not_available",
"message": "Отдел 'legal' не входит в тариф аккаунта.",
"param": "departments[0]",
"request_id": "req_51ab77c0"
}
}
У каждой ошибки — машиночитаемый code, человекочитаемое
message, указание на конкретный параметр и request_id
для разбора с поддержкой. Ошибки спроектированы так, чтобы интеграция могла
отличить «исправь запрос» (4xx) от «повтори позже» (429, 5xx) без чтения документации
между строк.
Принципы Целевая архитектура
Формат конкретных полей может уточняться — для этого и существует версионирование. Но базовые принципы контура приняты и пересматриваться не будут: они вытекают из опыта живых интеграций экосистемы Marisova и из здравого смысла. Если вы проектируете интеграцию, на эти шесть пунктов можно опираться уже сейчас.
voir_sk_… (секретные) и voir_pk_… (публичные,
только для чтения справочников). Токен принадлежит аккаунту, а не человеку;
ротация без простоя — выпускаем новый, старый живёт до истечения grace-периода.
Ключ никогда не логируется и не возвращается в ответах.
Idempotency-Key обязателен для POST-запросов: повтор с тем же
ключом возвращает первый результат, а не второй объект. Сеть ненадёжна —
дублей задач и запусков из-за ретраев быть не должно.
error.type / code / message / param / request_id едина для всех
эндпоинтов. Значения code — часть контракта: они не меняются в
пределах версии, чтобы ваш обработчик не развалился после нашего релиза.
X-RateLimit-Limit,
X-RateLimit-Remaining и X-RateLimit-Reset; при
превышении — честный 429 с Retry-After, а не молчаливое
замедление. Интеграция всегда знает, сколько у неё осталось.
Дорожная карта Целевая архитектура
Мы не называем сроки, потому что названная и не выполненная дата — та же фальшивая песочница, только в календаре. Порядок фаз — обязательство, которое мы готовы дать: сначала работоспособное ядро, потом события, потом публичный контур. Каждая фаза становится видимой на этой странице, когда доходит до дела.
Внутренний контур продукта: приём задачи, разбор AI CEO, назначение отделам, запуск агентов, сведение результата. Сначала для собственного интерфейса платформы — API-слой растёт из уже работающего ядра, а не проектируется в вакууме.
статус: не начатаШина событий продукта: подписки, HMAC-подписи, повторная доставка недоставленных уведомлений, журнал доставок. Без надёжных событий API превращается в опрос ради опроса — поэтому эта фаза идёт до публичного релиза.
статус: не начатаВыдача API-ключей, тарифные лимиты, документация с примерами на живых ответах и — только тогда — песочница, которая действительно рабочая, потому что за ней стоит настоящий сервер. До этого момента страница остаётся честным планом.
статус: не начатаВопросы и ответы
Нет. Публичного API не существует: продукт VOIR AI не запущен, у него нет ни сервера, ни выдачи ключей. Всё на этой странице — целевая архитектура, проектное решение о том, как API будет устроен. Если кто-то предлагает вам «ключ от API VOIR AI» — это не мы.
Чтобы партнёры и будущие клиенты заранее понимали контракт интеграции и могли оценить, подходит ли он им. Это честнее, чем заглушка «скоро»: мы показываем реальный проект интерфейса — ресурсы, методы, формат ошибок, модель авторизации — и прямо помечаем, что он не реализован.
Нет, и сознательно. Песочница, которая выглядит рабочей, но отвечает записанными сценариями, вводила бы в заблуждение — ровно то, против чего эта страница. Все примеры запросов и ответов здесь статичны и подписаны «пример — целевая архитектура».
Дат не называем. Порядок работ — в разделе дорожной карты: сначала ядро задач и агентов, затем шина событий и вебхуки, затем публичная выдача ключей с тарифными лимитами. Названная и сорванная дата обманывает так же, как фальшивый 200 OK в консоли.
В экосистеме Marisova, на которой мы строим, работают Telegram Bot API, Telegram Stars и ЮKassa API v3. Это наши внутренние соединения: они проверены запросами к живым эндпоинтам, не продаются и не являются частью продукта VOIR AI. Подробный разбор с фактами — на странице интеграций.
API — программный вход в те же восемь отделов, что видны в интерфейсе. POST /v1/tasks ставит задачу так же, как делегирование через AI CEO; запуски агентов соответствуют AI-агентам, задачи командам — AI-командам. Один и тот же разбор задачи, два входа: интерфейс и запрос.
Мы не продаём то, чего нет, — но и прятать планы не собираемся. Если ваша интеграция зависит от этого контракта, напишите: обсудим пилотное участие, порядок фаз и то, какие ресурсы нужны именно вам. А пока посмотрите, что уже реально работает в экосистеме и как устроена платформа.