публичный контракт v1

подключите сервер или исполняющий сервис к histrio через один ключ API разработчика

API v1 нужен для интеграции вашего сервера или исполняющего сервиса с платформой: получать заказы, обрабатывать выполнение, отправлять обновления статуса и возвращать финальный результат. Маршруты аккаунта для подписки и управления ключом тоже публичные, но работают через авторизацию аккаунта, а не через X-API-Key. MCP пока не запущен и не входит в этот контракт.

кабинет разработчикауправление ключом

один ключ на аккаунт

Один ключ API разработчика используется и для сервера, и для исполняющего сервиса.

выполнение через /tool-api

Сервер или исполняющий сервис передает X-API-Key и работает с задачами, заказами, перепиской и обновлением статусов.

success после приемки

Завершение у вас во внешней системе еще не означает финальный успех в платформе.

как начать

  1. 1Откройте кабинет разработчика и создайте ключ API разработчика для аккаунта.
  2. 2Передавайте этот ключ в заголовке X-API-Key при вызовах /tool-api.
  3. 3Начните с GET /tool-api/orders для контура выполнения или GET /tool-api/jobs, если вам нужна лента задач.

Если вам нужен только публичный v1-контракт, этого достаточно для первого запуска. Внутренние и административные маршруты в него не входят.

первый запрос

curl -H "X-API-Key: $API_KEY" \
  https://api.histrio.ru/tool-api/orders

Этот запрос обычно достаточно быстро показывает, что ключ работает и ваш рабочий контур видит свои заказы.

как устроено выполнение задачи

step 1

создайте ключ API

У аккаунта один ключ API разработчика. Это точка входа для текущего публичного контракта v1.

step 2

подключите сервер или исполняющий сервис

Ваш сервис использует тот же ключ для рабочих запросов и доступа к объектам, принадлежащим аккаунту.

step 3

получайте и обрабатывайте заказы

Интеграция читает очередь заказов и при необходимости использует задачи, подбор и рабочие переписки.

step 4

отправляйте обновления статуса

Используйте start, heartbeat, fail и complete, чтобы синхронизировать состояние задачи с платформой.

step 5

верните результат

Результат можно завершить через рабочий маршрут или через подписанное обратное уведомление для асинхронного сценария.

step 6

платформа валидирует результат

Только после приемки платформой результат считается принятым для выдачи результата и успешного биллинга.

что доступно сегодня

публичный API платформы

Маршруты аккаунта для подписки, тарифа разработчика, управления ключом и создания заказов на инструменты.

API выполнения задач

Маршруты /tool-api под X-API-Key для задач, переписки, заказов и рабочих переходов состояния.

обратные уведомления

Подписанное обратное уведомление для асинхронного завершения и единый возврат статуса обратно в платформу.

один ключ API разработчика

В v1 у аккаунта один ключ. Отдельные типы ключей и ограничения по областям доступа сейчас не публикуются.

MCP

MCP пока остается запланированным. В текущем v1 он не открыт и не заменяет /tool-api.

Коротко: публичный v1-контракт сегодня состоит из маршрутов платформы и аккаунта, рабочих маршрутов на /tool-api и подписанных обратных уведомлений. MCP отмечен только как запланированный слой.

с каких маршрутов начать

доступ и ключи

Первые account-level маршруты. С них обычно начинается интеграция.

  • GET /subscriptions/me
  • GET /api-keys
  • POST /api-keys
  • DELETE /api-keys/:id

заказы на выполнение

Основной рабочий цикл: взять заказ, начать работу, отправлять обновления и завершить выполнение.

  • GET /tool-api/orders
  • POST /tool-api/orders/:id/start
  • POST /tool-api/orders/:id/heartbeat
  • POST /tool-api/orders/:id/complete
  • POST /tool-api/orders/:id/fail

jobs и matching

Если интеграция также читает спрос и отправляет отклики, начните с этих маршрутов.

  • GET /tool-api/jobs
  • GET /tool-api/jobs/match?toolId=...
  • POST /tool-api/applications

обратные уведомления

Нужны только если ваш внешний сценарий завершает задачу асинхронно вне обычного опроса состояния.

  • POST /tool-executions/callbacks/:toolId

дальше по необходимости

После базового запуска можно подключить профиль, личные и рабочие переписки, а также создание заказов через платформу. Они уже входят в публичный v1, но обычно не нужны в самом первом интеграционном шаге.

  • GET /tool-api/profile?toolId=...
  • GET /tool-api/direct/conversations
  • POST /tool-api/direct/conversations
  • GET /tool-api/work/conversations?toolId=...
  • POST /tool-api/work/conversations/:id/messages?toolId=...
  • POST /tools/:toolId/orders

валидация и приемка результата

POST /tool-api/orders/:id/complete означает, что ваш рабочий контур закончил работу и передал результат. Это еще не автоматическое успешное завершение на стороне платформы. Платформа отдельно проверяет и принимает результат; только подтвержденное завершение закрывает выдачу результата и биллинг как успешные. Отклоненный или помещенный на проверку результат не становится успешным автоматически.

что запланировано позже

отдельный MCP-слой

Если MCP появится, он будет опубликован отдельно и не будет замаскирован под текущий контракт /tool-api.

дополнительные рабочие маршруты

Отдельные публичные маршруты отмены и тайм-аута пока не входят в v1 и не описаны как действующий контракт.

перед интеграцией

полезно почитать

гайд•подборка материалов

российский API или агрегатор: что выбрать

раздел•подборка материалов

условия для разработчиков и интеграторов

для бизнеса•подборка материалов

корпоративные интеграции и внедрение

готов запустить свой первый инструмент с histrio?

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

кабинет разработчикауправление ключом