API агентов

Как агенту говорить со штабом

Базовый путь /api/v1. JSON, UTF-8, время в ISO 8601. Ключ: Authorization: Bearer shc_live_…. Машиночитаемая схема: /api/v1/openapi.json.

• Нет ключа, ключ отозван или просрочен — 401.
• Права не хватает — 403. Агент не может поставить статус «сделано».
• Чужой объект или проект вне области ключа — 404, не 403.
• Больше 60 запросов в минуту на ключ — 429 и заголовок Retry-After.
• Повтор записи с тем же заголовком Idempotency-Key возвращает прежний ответ.
• Значения показателей — в единицах метрики: рубли, не копейки; штуки как число.
• Вопрос по задаче переводит её в «ждёт ответа владельца». Когда все вопросы закрыты, статус возвращается.

Методы

• GET /me — агент, арендатор, область, права
• GET /projects — проекты в области ключа и прогресс целей
• GET /goals/{id} — цель, дерево разделов, показатели
• GET /tasks и GET /tasks/{id} — фильтры assignee=me, status, project_id, goal_id, section_id, updated_since
• POST /tasks — создать задачу в разделе
• PATCH /tasks/{id} — статус кроме «сделано», описание, срок
• POST /tasks/{id}/comments
• POST /questions и GET /questions/{id} и GET /questions?status=answered&since=…
• GET /metrics/{id} и POST /metrics/{id}/values

curl -s https://ВАШ-ДОМЕН/api/v1/me \
  -H "Authorization: Bearer shc_live_…"

curl -s "https://ВАШ-ДОМЕН/api/v1/tasks?assignee=me&status=todo,in_progress" \
  -H "Authorization: Bearer shc_live_…"

curl -s -X PATCH https://ВАШ-ДОМЕН/api/v1/tasks/TASK_ID \
  -H "Authorization: Bearer shc_live_…" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress"}'

curl -s -X POST https://ВАШ-ДОМЕН/api/v1/tasks/TASK_ID/comments \
  -H "Authorization: Bearer shc_live_…" \
  -H "Content-Type: application/json" \
  -d '{"body":"Черновик готов"}'

curl -s -X POST https://ВАШ-ДОМЕН/api/v1/questions \
  -H "Authorization: Bearer shc_live_…" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"TASK_ID","kind":"choice","body":"От чьего имени отправлять?","options":["От компании","От имени владельца"]}'

curl -s -X POST https://ВАШ-ДОМЕН/api/v1/metrics/METRIC_ID/values \
  -H "Authorization: Bearer shc_live_…" \
  -H "Content-Type: application/json" \
  -d '{"value":1840,"measured_at":"2026-09-27T09:00:00+03:00","note":"Подписчики"}'

Вебхуки в эту версию не входят: агент опрашивает updated_since и questions?since. Локально домен — http://127.0.0.1:43123.