Інтеграція REST API CloudTAK: підключення зовнішніх систем до тактичної мережі

Автор: Інженерна команда Corvus Intelligence · Про команду →

29 травня 2026 12 хв читання

REST API CloudTAK перетворює TAK-сервер з пасивного ретранслятора на активний хаб інтеграції. Замість того щоб вимагати від кожного джерела даних підтримки нативного CoT через TCP/TLS — єдиний шлях до застарілого TAK Server — CloudTAK надає повну HTTP та WebSocket поверхню, яку може викликати будь-яка сучасна система: масиви сенсорів, логістичні платформи, конвеєри AI-висновків, канали SIGINT та кастомні дашборди. Цей посібник детально охоплює всі основні API-поверхні: автентифікацію, ін'єкцію CoT, стрімінг треків у реальному часі, управління місіями, завантаження пакетів даних, адміністрування груп, вебхуки та AI-копілот TAKpilot як приклад інтеграції. Якщо вам потрібно спочатку розгорнути сервер CloudTAK, перегляньте наш супровідний посібник з розгортання сервера CloudTAK.

Автентифікація: JWT-токени, API-ключі та областя доступу

REST API CloudTAK забезпечує автентифікацію на кожному ендпойнті, крім перевірки стану (GET /api/health). Підтримуються два типи облікових даних, обидва передаються як HTTP-заголовок Authorization: Bearer <token>.

JWT-токени

JWT-токени є короткостроковими та видаються для кожної сесії користувача. Отримайте токен, надіславши облікові дані на ендпойнт входу:

curl -s -X POST https://tak.yourdomain.com:8443/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "operator01", "password": "s3cur3p@ss"}' \
  | jq -r '.token'

Тіло відповіді містить token (рядок JWT) та expires (Unix-мітка часу). Стандартний TTL — 86400 секунд (24 години); налаштовується через CLOUDTAK_JWT_TTL. JWT-токени містять роль та членство в групах як претензії, тому перевірка дозволів є безстановою.

API-ключі

API-ключі є довгостроковими токенами, підходящими для автоматизованих інтеграцій сервіс-до-сервісу. Генеруйте їх через адміністративний API:

curl -s -X POST https://tak.yourdomain.com:8443/api/token \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sensor-array-east",
    "scopes": ["cot:write"],
    "rateLimit": 500
  }' | jq -r '.token'

Підтримувані областя доступу та їх призначення:

Область	Надає доступ до
`cot:write`	Ін'єкція CoT-подій через POST /api/cot
`cot:read`	Запит історичних треків через GET /api/cot
`events:subscribe`	Підключення до WebSocket-потоку на /api/ws
`mission:write`	Створення, оновлення та видалення місій
`package:write`	Завантаження пакетів даних та вкладень
`group:write`	Створення груп та управління членством
`admin`	Всі областя плюс управління користувачами та конфігурація сервера

Відкличте ключ у будь-який час: DELETE /api/token/{id}. Перелічіть активні ключі через GET /api/token.

Базова URL та ліміти запитів

Усі REST-ендпойнти доступні за адресою https://<host>:8443/api/. Стандартний глобальний ліміт — 100 запитів на секунду на API-ключ. Відповіді HTTP 429 містять заголовок Retry-After. Специфікація OpenAPI доступна за адресою GET /api/docs.

Ін'єкція CoT: POST /api/cot

Ендпойнт ін'єкції CoT є основним шляхом для надсилання звітів про позицію, маркерів контактів, сповіщень та будь-яких інших CoT-подій до тактичної картини із зовнішніх систем. Він приймає як необроблений CoT XML, так і зручний JSON-формат.

XML-корисне навантаження

Для систем, які вже генерують нативний CoT XML — сенсори, застарілі ATAK-плагіни, канали радарів — надсилайте необроблений конверт безпосередньо:

curl -s -X POST https://tak.yourdomain.com:8443/api/cot \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/xml" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<event version="2.0"
       uid="sensor-east-001"
       type="a-f-G-U-C"
       how="m-g"
       time="2026-05-29T14:32:00Z"
       start="2026-05-29T14:32:00Z"
       stale="2026-05-29T14:37:00Z">
  <point lat="50.4501" lon="30.5234" hae="145.0" ce="10.0" le="5.0"/>
  <detail>
    <contact callsign="SENSOR-EAST-01"/>
    <remarks>Контакт наземного радара, швидкість 12 км/год, курс 045</remarks>
    <group name="Surveillance" role="Team Member"/>
  </detail>
</event>'

Обов'язкові поля CoT: uid (унікальний рядок для сутності — повторне використання того самого UID оновлює існуючий трек), type (рядок ієрархії типів CoT), time, start, stale та елемент <point> з lat, lon, hae, ce та le.

JSON-корисне навантаження

Для інтеграцій на сучасних стеках без бібліотек CoT XML використовуйте JSON-формат:

curl -s -X POST https://tak.yourdomain.com:8443/api/cot \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "logistics-truck-07",
    "type": "a-f-G-U-C",
    "callsign": "LOG-07",
    "lat": 50.4610,
    "lon": 30.5190,
    "hae": 138.0,
    "ce": 5.0,
    "le": 3.0,
    "staleSeconds": 300,
    "remarks": "Конвой постачання, очікуваний час прибуття на КПП 14:45Z",
    "group": "Logistics",
    "role": "Team Member"
  }'

CloudTAK серіалізує цей JSON у повний CoT XML-конверт внутрішньо. Успішна ін'єкція повертає HTTP 201 з UID CoT у тілі відповіді. Подія негайно поширюється на всіх підписаних клієнтів та WebSocket-потік.

Стрімінг треків: WebSocket /api/ws

Для споживання тактичної картини в реальному часі — побудови кастомного дашборда, подачі до AI-конвеєра, архівування треків у data lake — ендпойнт WebSocket забезпечує безперервний, низьколатентний потік CoT-подій.

Підключення та підписка

// Приклад Node.js з бібліотекою 'ws'
const WebSocket = require('ws');

const ws = new WebSocket('wss://tak.yourdomain.com:8443/api/ws', {
  headers: { 'Authorization': `Bearer ${process.env.CLOUDTAK_API_KEY}` }
});

ws.on('open', () => {
  // Надсилаємо фільтр підписки одразу після підключення
  ws.send(JSON.stringify({
    type: 'subscribe',
    filter: {
      groups: ['Surveillance', 'Logistics'],
      bbox: [29.5, 50.0, 31.5, 51.0],
      types: ['a-f-G', 'a-h-G', 'a-u-G']
    }
  }));
});

ws.on('message', (data) => {
  const event = JSON.parse(data);
  if (event.type === 'cot') {
    console.log(`Трек: ${event.payload.uid} на ${event.payload.lat},${event.payload.lon}`);
  } else if (event.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }));
  }
});

Сервер надсилає повідомлення ping кожні 30 секунд. Клієнти повинні відповідати pong протягом 10 секунд, інакше з'єднання закриється.

Оновлення фільтрів на активному з'єднанні

Надсилайте нове повідомлення subscribe у будь-який час для заміни поточного фільтра — без відключення або перепідключення. Це корисно для відстеження операції при зміні географічного района.

API місій: створення, оновлення, видалення та призначення

Місії в CloudTAK — це іменовані операційні контексти, що групують треки, пакети даних та користувачів. API місій дозволяє зовнішнім системам програматично створювати місії — наприклад, інструмент планування, що генерує місії з бойового порядку та завантажує їх до CloudTAK перед початком операції.

Створення місії

curl -s -X POST https://tak.yourdomain.com:8443/api/mission \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ОПЕРАЦІЯ CLEARWATER",
    "description": "Захоплення блокпоста, Фаза 1",
    "classification": "UNCLASSIFIED",
    "bbox": [30.10, 50.35, 30.25, 50.45],
    "groups": ["Alpha-Company", "ISR-Detachment"]
  }' | jq '{uid: .uid, name: .name}'

Відповідь включає uid місії (UUID), що використовується у всіх наступних операціях. Масив groups негайно призначає місію іменованим групам. Призначте додаткові групи пізніше через PATCH /api/mission/{uid}/groups.

Оновлення та видалення місій

Оновіть метадані місії через PATCH /api/mission/{uid}. Видаліть місію через DELETE /api/mission/{uid}. М'яке видалення доступне через PATCH /api/mission/{uid} з "archived": true.

API пакетів даних: MBTiles, KMZ, GeoJSON та версіонування

Пакети даних, прикріплені до місій, розповсюджують картографічні шари та довідкові дані на польові пристрої. CloudTAK приймає три формати: MBTiles, KMZ та GeoJSON. Завантаження використовує multipart form data:

# Завантаження шару MBTiles для офлайн-покриття карти
curl -s -X POST \
  https://tak.yourdomain.com:8443/api/mission/${MISSION_UID}/attachment \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/data/aoi-sector-north.mbtiles" \
  -F "name=Базова карта сектору Північ" \
  -F "contentType=application/vnd.mbtiles" \
  | jq '{attachmentId: .id, version: .version}'

CloudTAK перевіряє формат файлу при завантаженні. Кожне завантаження створює нову версію. Щоб перелічити всі версії вкладення:

GET /api/mission/{missionUid}/attachment/{attachmentId}/versions

Клієнти завжди отримують останню версію, якщо конкретна версія не закріплена у конфігурації місії. Окремі картографічні шари (не прив'язані до конкретної місії) завантажуються через POST /api/layer. Для офлайн-першого польового розгортання перегляньте наш посібник з MBTiles та PMTiles для офлайн-карт.

Групи та канали: фільтрація видимості та контроль доступу до треків

Групи CloudTAK реалізують сегрегацію видимості треків. Трек із тегом групи видимий лише підключеним клієнтам — членам цієї групи. Це забезпечує розподіл за принципом необхідності знання в межах спільного TAK-сервера.

Створення групи та призначення користувачів

# Створення групи
curl -s -X POST https://tak.yourdomain.com:8443/api/group \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ISR-Detachment", "description": "Розвідувальний підрозділ"}' \
  | jq '.id'

# Додавання користувача до групи
curl -s -X POST https://tak.yourdomain.com:8443/api/group/ISR-Detachment/user \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "isr-analyst-01"}'

Членство в групі контролює три речі: які треки клієнт отримує у WebSocket-потоці, які місії відображаються у стрічці місій клієнта, та які пакети даних розповсюджуються при підключенні. Клієнт може одночасно належати до кількох груп. Треки без тега групи видимі всім користувачам на сервері.

TAKpilot як приклад інтеграції

TAKpilot — AI-копілот Corvus Intelligence для операцій на базі TAK. Це конкретний приклад глибокої інтеграції API CloudTAK: TAKpilot підписується на WebSocket-потік треків, обробляє команди природною мовою від операторів та виконує їх як виклики API CloudTAK — перетворюючи людський намір безпосередньо в оновлення тактичної картини.

Команда природною мовою, наприклад "позначити координати 38T YQ 45123 67890 як ворожий контакт, призначити до місії Alpha-Company", ініціює наступну послідовність API у TAKpilot:

Конвертація MGRS 38T YQ 45123 67890 у десяткові градуси (внутрішня конвертація, без виклику API).
POST /api/cot з типом a-h-G (ворожа наземна), конвертованими координатами та системно-генерованим позивним з префіксом AI-HOSTILE-.
GET /api/mission?name=Alpha-Company для визначення UID місії за частковою назвою.
POST /api/mission/{uid}/cot для асоціації UID ін'єктованої CoT-події з місією.
Відповідь оператору через чат-інтерфейс TAKpilot з підтвердженням дії, включаючи згенерований позивний та координати.

TAKpilot також використовує WebSocket-потік реактивно: коли новий ворожий трек (тип a-h) з'являється в межах відстежуваного обмежувального прямокутника, він може автоматично ініціювати аналіз загрозливої схеми та опублікувати синтезовану оцінку як CoT-ремарку, видиму операторській групі — без очікування явної команди.

Вебхуки: підписка на події та ретрансляція до зовнішніх систем

Вебхуки дозволяють CloudTAK надсилати події до зовнішніх систем замість того, щоб вимагати від цих систем опитування REST API або підтримки постійного WebSocket-з'єднання.

Реєстрація вебхука

curl -s -X POST https://tak.yourdomain.com:8443/api/webhook \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "kafka-bridge",
    "url": "https://integration.yourdomain.com/cloudtak-events",
    "events": ["new_track", "mission_update", "user_join"],
    "secret": "hmac_signing_secret_32chars_min",
    "active": true
  }' | jq '{id: .id, status: .status}'

CloudTAK підписує кожну доставку вебхука підписом HMAC-SHA256, обчисленим над необробленим JSON-тілом за допомогою вашого секрету, доставленим у заголовку X-CloudTAK-Signature. Перевіряйте підпис на стороні отримувача для запобігання підробленим викликам вебхука:

// Отримувач вебхука Express.js з перевіркою підпису
const crypto = require('crypto');

app.post('/cloudtak-events', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['x-cloudtak-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Невідповідність підпису');
  }

  const event = JSON.parse(req.body);
  // Ретрансляція до Kafka, Slack, SIEM тощо
  kafkaProducer.send({ topic: 'tak-events', messages: [{ value: req.body }] });
  res.status(200).send('OK');
});

Збої доставки (відповідь не 2xx або тайм-аут після 5 секунд) ініціюють повторні спроби з експоненціальним відступом: 1, 2, 4, 8, 16 секунд — потім подія відкидається та фіксується. Переглядайте історію доставки через GET /api/webhook/{id}/deliveries.

Підтримувані типи подій вебхука

new_track — новий UID вперше з'являється на картині.
track_stale — мітка часу застарілості треку минула без оновлення.
mission_update — місія була створена, змінена, архівована або видалена.
user_join — новий клієнт підключився та пройшов автентифікацію.
user_leave — клієнт відключився або сесія завершилася.
cot_alert — отримано CoT-подію з префіксом типу b-a (тривога/сигнал тривоги).

Підключіть ваші системи до екосистеми TAK

Ми будуємо інтеграції API CloudTAK для сенсорних мереж, логістичних платформ, конвеєрів AI-висновків та кастомних дашбордів C2 — та підсилюємо їх TAKpilot, нашим AI-копілотом для тактичних операцій.

AI-копілот TAKpilot → Замовити брифінг

Цей аналіз підготовлений інженерами Corvus Intelligence, які розробляють критично важливе програмне забезпечення для оборонних та урядових організацій. Дізнайтеся про нашу команду →

Часті запитання

Які методи автентифікації підтримує REST API CloudTAK?

REST API CloudTAK підтримує два методи автентифікації: JWT-токени на носії та статичні API-ключі. JWT-токени видаються через POST /api/login з обліковими даними та закінчуються після налаштовуваного TTL (стандартно 24 години). API-ключі є довгостроковими токенами, згенерованими через адміністративний API, та підходять для інтеграцій сервіс-до-сервісу. Для виробничих інтеграцій перевагу мають API-ключі, оскільки вони можуть бути обмежені конкретними дозволами та відкликані незалежно.

Який правильний Content-Type для ін'єкції CoT через REST API?

Ендпойнт ін'єкції CoT CloudTAK (POST /api/cot) приймає два типи вмісту: application/xml для необроблених CoT XML-корисних навантажень та application/json для JSON-обгортки, яку CloudTAK внутрішньо конвертує в CoT XML. Завжди вказуйте заголовок Content-Type явно.

Як фільтрувати WebSocket-потік треків за групою або обмежувальним прямокутником?

Ендпойнт WebSocket CloudTAK (/api/ws) приймає об'єкт фільтра підписки під час підключення. Фільтр підтримує три поля: groups (масив назв груп), bbox (обмежувальний прямокутник GeoJSON [minLon, minLat, maxLon, maxLat]) та types (масив рядків типів CoT). Ви можете оновлювати фільтри на активному з'єднанні, надсилаючи нове повідомлення фільтра.

Який ліміт запитів на ендпойнт ін'єкції CoT?

Стандартний ліміт CloudTAK — 100 CoT-подій на секунду на API-ключ. Це налаштовується через змінну середовища CLOUDTAK_COT_RATE_LIMIT або для кожного ключа через адміністративний API. При перевищенні ліміту API повертає HTTP 429 Too Many Requests із заголовком Retry-After у секундах.

Як створити місію та прикріпити до неї пакети даних через API?

Створення місії — двоетапний процес: спочатку POST до /api/mission з назвою, описом та необов'язковим призначенням групи, щоб отримати назад UID місії. Потім POST до /api/mission/{uid}/attachment з тілом multipart/form-data, що містить файл пакета даних (MBTiles, KMZ або GeoJSON). CloudTAK зберігає вкладення та робить його доступним для завантаження підписниками місії.

Чи можна завантажити картографічні шари MBTiles через API CloudTAK?

Так. POST до /api/layer з тілом multipart/form-data, що містить файл MBTiles та метадані (name, minZoom, maxZoom, bounds). CloudTAK перевіряє формат MBTiles, витягує межі тайлів та рівні масштабу з таблиці метаданих та робить шар доступним для всіх підключених клієнтів. PMTiles також підтримується через той самий ендпойнт.

Як працюють вебхуки в CloudTAK?

Вебхуки CloudTAK реєструються через POST /api/webhook з цільовою URL, типами подій та необов'язковим секретом HMAC для підписання корисного навантаження. При спрацюванні відповідної події CloudTAK надсилає HTTP POST на вашу цільову URL з JSON-тілом. При збоях доставки CloudTAK повторює з експоненціальним відступом до 5 разів.

Як TAKpilot використовує API CloudTAK для виконання команд природною мовою?

TAKpilot отримує команди природною мовою від операторів та розкладає їх на виклики API CloudTAK. Команда позначити місцезнаходження стає POST /api/cot з відповідним типом CoT та координатами, конвертованими з MGRS. Команда створити місію стає POST /api/mission. TAKpilot підтримує контекст сесії, щоб наступні команди розв'язували посилання з попередніх відповідей API. Він також споживає WebSocket-потік реактивно — нові ворожі треки в межах відстежуваного района ініціюють автоматичні оцінки загрози.

На які типи подій можна підписатися через WebSocket CloudTAK?

WebSocket-потік CloudTAK генерує п'ять типів подій: cot (CoT XML-подія від будь-якого підключеного клієнта або джерела API), track_update (дельта-оновлення позиції або атрибутів існуючого треку), mission_update (місія створена, змінена або видалена), user_event (клієнт підключився, відключився або змінив позивний/команду) та system_event (серверні події). Підписуйтеся вибірково, використовуючи поле фільтра types.

Як версіонувати пакети даних, прикріплені до місій?

CloudTAK зберігає історію версій для кожного вкладення пакета даних. Кожне завантаження до /api/mission/{uid}/attachment створює нову версію. Поточна (остання) версія обслуговується за замовчуванням. Щоб отримати конкретну версію, додайте параметр запиту version: GET /api/mission/{uid}/attachment/{attachmentId}?version=2. Це корисно для підготовки оновлення карти перед відправленням на польові пристрої.