← К схеме

Public API

контракт · построй свою поверхность

Любая поверхность — клиент одного контракта

Web App, MCP, Slack, Telegram, Mattermost, расширение — все они лишь клиенты одного публичного API. Развернули Achilles и хотите свою поверхность — Teams-бот, CLI, корпоративный портал — подключаете её тем же входом.

Achilles — API-first: каждая поверхность, наша и ваша, — клиент одного публичного контракта. Контракт — это курируемый стабильный срез (/public/v1). Наши MCP, Slack, Telegram, Mattermost и расширение — референс-реализации: стройте так же. Один движок диалога за контрактом →

01

Контракт

Наружу — узкий набор операций под версией в пути: старая версия живёт до объявленного вывода новой.

  • search находки + источники, read-only
  • ask v2 полный ход чата — готовый ответ с источниками

OpenAPI отдаётся из коробки (FastAPI) — клиент генерится по схеме. Транспорт — обычный REST/JSON; MCP — тот же контракт в обёртке для AI-клиентов.

02

Авторизация

Свой механизм не изобретаем — тот же вход, что у двери MCP.

Ключ сводится к user_id → роль → ACL. Область ключа лишь сужает права — ACL поверх, в обход не пройти.

03

Личность

Единственный по-настоящему новый кусок — как пользователи вашей поверхности становятся личностями Achilles. Мост — identity_mapping со своим source — как 'slack' у Slack или 'telegram' у Telegram.

Каков мост — зависит от того, кого поверхность представляет: два класса ниже. Учётку всё равно заводит админ приглашением — членство в вашей системе доступа не даёт.

04

Управление

Кастомная поверхность под тем же надзором, что родные — отдельного режима нет.

  • Рубильник и ключи. Доступ закрывается разом деактивацией ключа; владелец заводит и гасит ключи в профиле, надзор Owner/Admin — на экране ключей.
  • Лимит и метка. Каждый вызов под лимитом частоты и метится на ключ — использование видно на экране ключей; текст запроса не логируется.

Два класса поверхностей

Персональная Сервисная
Принцип ключ = один сотрудник поверхность отвечает за многих
Личность ключ → его user_id свой source в identity_mapping, каждый внешний → user_id
Доступ личный ключ владельца сервисный ключ + резолв личности на каждый запрос
Референс MCP · Extension Slack · Telegram · Mattermost

Сервисная поверхность ходит через общий путь «действую от имени» — сервисный ключ со своим source и предъявление личности на каждом запросе. Slack, Telegram и Mattermost — лишь референсы этого механизма, не код для форка: ваша поверхность пользуется тем же путём, не трогая платформу.

Наши поверхности — референс

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

MCP персональная дверь с одним инструментом для AI-клиента Slack поверхность за многих: мост личности + отложенная доставка Telegram тот же класс: мост личности, граница беседы по /new Mattermost тот же класс на self-hosted сервере: мост личности, тред = беседа Extension персональный клиент в браузере поверх любой страницы

Контракт вызова

запрос 
POST /public/v1/search
Authorization: Bearer ach_…

{
  "query": "статус релиза 4.2",
  "limit": 8
}
ответ 
200 OK

{
  "results": [
    {
      "title": "RELEASE-482",
      "snippet": "Релиз 4.2 в регресс-тестах…",
      "source": "ticket",
      "url": "https://jira…/RELEASE-482",
      "score": 0.82
    }
  ],
  "degraded": false
}

Поиск идёт под ACL владельца ключа — что ему не видно, в выдачу не попадёт. Синтез ответа — на стороне клиента; degraded отмечает выдачу без векторной ноги (эмбеддер молчал). v2 добавит POST /public/v1/ask — готовый ответ с источниками одним вызовом.

API