CloudTAK REST API Integration: Externe Systeme mit dem taktischen Netzwerk verbinden

Von Corvus Intelligence Engineering Team · Über das Team →

29. Mai 2026 12 Min. Lesezeit

Die REST API von CloudTAK verwandelt einen TAK-Server von einem passiven Relay in einen aktiven Integrations-Hub. Statt jede Datenquelle zur Unterstützung von nativem CoT über TCP/TLS zu zwingen — dem einzigen Pfad in den Legacy-TAK-Server — bietet CloudTAK eine vollständige HTTP- und WebSocket-Oberfläche, die jedes moderne System aufrufen kann: Sensor-Arrays, Logistikplattformen, KI-Inferenz-Pipelines, SIGINT-Feeds und benutzerdefinierte Dashboards. Dieser Leitfaden deckt alle wichtigen API-Oberflächen im Detail ab: Authentifizierung, CoT-Injektion, Echtzeit-Track-Streaming, Missionsverwaltung, Datenpaket-Upload, Gruppenverwaltung, Webhooks und den TAKpilot KI-Copiloten als Integrationsbeispiel. Falls Sie zuerst einen CloudTAK-Server aufsetzen müssen, lesen Sie unseren Begleitleitfaden zum CloudTAK-Server-Deployment.

Authentifizierung: JWT-Tokens, API-Schlüssel und Scopes

Die CloudTAK REST API erzwingt Authentifizierung auf jedem Endpunkt außer der Gesundheitsprüfung (GET /api/health). Zwei Credential-Typen werden unterstützt, beide als HTTP-Header Authorization: Bearer <token> übergeben.

JWT-Tokens

JWT-Tokens sind kurzlebig und werden pro Benutzersitzung ausgestellt. Erhalten Sie eines, indem Sie Anmeldedaten an den Login-Endpunkt senden:

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'

Die Standard-TTL beträgt 86400 Sekunden (24 Stunden); konfigurierbar über CLOUDTAK_JWT_TTL. JWTs tragen die Rolle des Benutzers und Gruppenmitgliedschaften als Claims, sodass Berechtigungsprüfungen zustandslos sind.

API-Schlüssel

API-Schlüssel sind langlebige Tokens für automatisierte Service-zu-Service-Integrationen. Generieren Sie sie über die Admin-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'

Unterstützte Scopes und was sie freischalten:

Scope	Gewährt Zugriff auf
`cot:write`	CoT-Events über POST /api/cot injizieren
`cot:read`	Historische Tracks über GET /api/cot abfragen
`events:subscribe`	Mit dem WebSocket-Stream bei /api/ws verbinden
`mission:write`	Missionen erstellen, aktualisieren und löschen
`package:write`	Datenpakete und Anhänge hochladen
`group:write`	Gruppen erstellen und Mitgliedschaft verwalten
`admin`	Alle Scopes plus Benutzerverwaltung und Server-Konfiguration

Widerrufen Sie einen Schlüssel jederzeit: DELETE /api/token/{id}. Aktive Schlüssel auflisten: GET /api/token.

Basis-URL und Rate-Limits

Alle REST-Endpunkte werden unter https://<host>:8443/api/ bereitgestellt. Das Standard-Globale Rate-Limit beträgt 100 Anfragen pro Sekunde pro API-Schlüssel. HTTP-429-Antworten enthalten einen Retry-After-Header. Die OpenAPI-Spezifikation ist unter GET /api/docs verfügbar.

CoT-Injektion: POST /api/cot

Der CoT-Injektions-Endpunkt ist der primäre Pfad zum Einspeisung von Positionsberichten, Kontaktmarkierungen, Alerts und beliebigen anderen CoT-Events aus externen Systemen in das taktische Lagebild.

XML-Payload

Für Systeme, die bereits natives CoT XML erzeugen, senden Sie den rohen Envelope direkt:

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>Bodenradar-Kontakt, Geschwindigkeit 12 km/h, Kurs 045</remarks>
    <group name="Surveillance" role="Team Member"/>
  </detail>
</event>'

JSON-Payload

Für Integrationen auf modernen Stacks ohne CoT-XML-Bibliotheken verwenden Sie das JSON-Format:

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": "Nachschubkonvoi, voraussichtliche Ankunft Checkpoint 14:45Z",
    "group": "Logistics",
    "role": "Team Member"
  }'

CloudTAK serialisiert diesen JSON intern zu einem vollständigen CoT-XML-Envelope. Eine erfolgreiche Injektion gibt HTTP 201 zurück. Das Event wird sofort an alle abonnierten Clients und den WebSocket-Stream propagiert.

Track-Streaming: WebSocket /api/ws

Für die Echtzeit-Konsumierung des taktischen Lagebilds bietet der WebSocket-Endpunkt einen kontinuierlichen, latenzsarmen Stream von CoT-Events.

Verbinden und abonnieren

// Node.js-Beispiel mit der 'ws'-Bibliothek
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(`Track: ${event.payload.uid} bei ${event.payload.lat},${event.payload.lon}`);
  } else if (event.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }));
  }
});

Der Server sendet alle 30 Sekunden eine ping-Nachricht. Clients müssen innerhalb von 10 Sekunden mit pong antworten, sonst wird die Verbindung geschlossen.

Filter auf einer aktiven Verbindung aktualisieren

Senden Sie jederzeit eine neue subscribe-Nachricht, um den aktuellen Filter zu ersetzen — ohne Trennung oder Neuverbindung.

Missions-API: erstellen, aktualisieren, löschen und zuweisen

Missionen in CloudTAK sind benannte operative Kontexte, die Tracks, Datenpakete und Benutzer gruppieren. Die Missions-API ermöglicht externen Systemen die programmatische Erstellung von Missionen.

Eine Mission erstellen

curl -s -X POST https://tak.yourdomain.com:8443/api/mission \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OPERATION CLEARWATER",
    "description": "Checkpoint-Einnahme, Phase 1",
    "classification": "UNCLASSIFIED",
    "bbox": [30.10, 50.35, 30.25, 50.45],
    "groups": ["Alpha-Company", "ISR-Detachment"]
  }' | jq '{uid: .uid, name: .name}'

Die Antwort enthält die Mission-uid (eine UUID). Aktualisieren Sie Missions-Metadaten mit PATCH /api/mission/{uid}. Löschen Sie eine Mission mit DELETE /api/mission/{uid}.

Datenpaket-API: MBTiles, KMZ, GeoJSON und Versionierung

An Missionen angehängte Datenpakete verteilen Kartenebenen und Referenzdaten an Feldgeräte. CloudTAK akzeptiert drei Formate: MBTiles, KMZ und GeoJSON:

# MBTiles-Layer für Offline-Kartenkopie hochladen
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=Sektor Nord Basiskarte" \
  -F "contentType=application/vnd.mbtiles" \
  | jq '{attachmentId: .id, version: .version}'

Alle Versionen eines Anhangs auflisten:

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

Eigenständige Kartenebenen werden über POST /api/layer hochgeladen. Für Offline-Einsätze: MBTiles und PMTiles für Offline-Karten.

Gruppen und Kanäle: Sichtbarkeitsfilterung und Track-Zugangskontrolle

CloudTAK-Gruppen implementieren Track-Sichtbarkeitssegregation. Ein Track mit einem Gruppen-Tag ist nur für verbundene Clients sichtbar, die Mitglieder dieser Gruppe sind. Dies ermöglicht Need-to-know-Trennung innerhalb eines gemeinsamen TAK-Servers.

Eine Gruppe erstellen und Benutzer zuweisen

# Gruppe erstellen
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": "Aufklärungszelle"}' \
  | jq '.id'

# Benutzer zur Gruppe hinzufügen
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"}'

Ein Client kann gleichzeitig mehreren Gruppen angehören — er erhält die Vereinigung aller Track-Sets über seine Gruppen. Tracks ohne Gruppen-Tag sind für alle Benutzer auf dem Server sichtbar.

TAKpilot als Integrationsbeispiel

TAKpilot ist Corvus Intelligences KI-Copilot für TAK-basierte Operationen. Es ist ein konkretes Beispiel für eine tiefe CloudTAK-API-Integration: TAKpilot abonniert den WebSocket-Track-Stream, verarbeitet natürlichsprachliche Befehle von Operatoren und führt sie als CloudTAK-API-Aufrufe aus.

Ein natürlichsprachlicher Befehl wie "Gitter 38T YQ 45123 67890 als feindlichen Kontakt markieren, Alpha-Company-Mission zuweisen" löst folgende API-Sequenz in TAKpilot aus:

MGRS 38T YQ 45123 67890 in Dezimalgrad konvertieren (interne Konvertierung, kein API-Aufruf).
POST /api/cot mit Typ a-h-G (feindlich Boden), konvertierten Koordinaten und systemgeneriertem Rufzeichen mit Präfix AI-HOSTILE-.
GET /api/mission?name=Alpha-Company zur Auflösung der Mission-UID.
POST /api/mission/{uid}/cot zum Verknüpfen des injizierten CoT-Events mit der Mission.
Antwort an den Operator über die TAKpilot-Chat-Schnittstelle mit Bestätigung der Aktion.

TAKpilot nutzt den WebSocket-Stream auch reaktiv: Wenn ein neuer feindlicher Track (Typ a-h) in einem überwachten Begrenzungsrahmen erscheint, kann automatisch eine Bedrohungsanalyse ausgelöst werden.

Webhooks: Events abonnieren und an externe Systeme weiterleiten

Webhooks ermöglichen CloudTAK, Events an externe Systeme zu pushen, anstatt dass diese Systeme die REST API abfragen oder eine persistente WebSocket-Verbindung aufrechterhalten müssen.

Einen Webhook registrieren

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 signiert jede Webhook-Lieferung mit einer HMAC-SHA256-Signatur, die im Header X-CloudTAK-Signature geliefert wird. Überprüfen Sie die Signatur auf Ihrer Empfängerseite:

// Express.js Webhook-Empfänger mit Signaturprüfung
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('Signatur-Mismatch');
  }

  const event = JSON.parse(req.body);
  // An Kafka, Slack, SIEM etc. weiterleiten
  kafkaProducer.send({ topic: 'tak-events', messages: [{ value: req.body }] });
  res.status(200).send('OK');
});

Lieferfehler lösen Wiederholungsversuche mit exponentiellem Backoff aus: 1, 2, 4, 8, 16 Sekunden. Lieferhistorie anzeigen: GET /api/webhook/{id}/deliveries.

Unterstützte Webhook-Event-Typen

new_track — eine neue UID erscheint erstmals auf dem Lagebild.
track_stale — der Stale-Zeitstempel eines Tracks ist ohne Aktualisierung abgelaufen.
mission_update — eine Mission wurde erstellt, geändert, archiviert oder gelöscht.
user_join — ein neuer Client hat sich verbunden und authentifiziert.
user_leave — ein Client hat die Verbindung getrennt oder die Sitzung ist abgelaufen.
cot_alert — ein CoT-Event mit dem Typprefix b-a (Alarm) wurde empfangen.

Ihre Systeme mit dem TAK-Ökosystem verbinden

Wir bauen CloudTAK-API-Integrationen für Sensornetzwerke, Logistikplattformen, KI-Inferenz-Pipelines und benutzerdefinierte C2-Dashboards — und betreiben sie mit TAKpilot, unserem KI-Copiloten für taktische Operationen.

TAKpilot KI-Copilot → Briefing buchen

Diese Analyse wurde von Corvus Intelligence-Ingenieuren erstellt, die unternehmenskritische Software für Verteidigungs- und Regierungsorganisationen entwickeln. Mehr über unser Team →

Häufig gestellte Fragen

Welche Authentifizierungsmethoden unterstützt die CloudTAK REST API?

Die CloudTAK REST API unterstützt zwei Authentifizierungsmethoden: JWT Bearer-Tokens und statische API-Schlüssel. JWT-Tokens werden über POST /api/login ausgestellt und laufen nach einer konfigurierbaren TTL ab (Standard 24 Stunden). API-Schlüssel sind langlebige Tokens, die über die Admin-API generiert werden und für Service-zu-Service-Integrationen geeignet sind. Für Produktionsintegrationen werden API-Schlüssel bevorzugt, da sie auf spezifische Berechtigungen eingeschränkt werden können.

Was ist der korrekte Content-Type für CoT-Injektion über die REST API?

Der CloudTAK CoT-Injektions-Endpunkt (POST /api/cot) akzeptiert zwei Content-Types: application/xml für rohe CoT XML-Payloads und application/json für einen JSON-Wrapper, den CloudTAK intern in CoT XML konvertiert. Geben Sie den Content-Type-Header immer explizit an.

Wie filtere ich den WebSocket-Track-Stream auf eine bestimmte Gruppe oder einen Begrenzungsrahmen?

Der CloudTAK WebSocket-Endpunkt (/api/ws) akzeptiert ein Abonnement-Filterobjekt zum Verbindungszeitpunkt. Der Filter unterstützt drei Felder: groups (Array von Gruppennamen), bbox (GeoJSON Begrenzungsrahmen [minLon, minLat, maxLon, maxLat]) und types (Array von CoT-Typ-Strings). Sie können Filter auf einer aktiven Verbindung aktualisieren.

Was ist das Rate-Limit am CoT-Injektions-Endpunkt?

Das Standard-CloudTAK-Rate-Limit beträgt 100 CoT-Events pro Sekunde pro API-Schlüssel. Konfigurierbar über die Umgebungsvariable CLOUDTAK_COT_RATE_LIMIT oder pro Schlüssel über die Admin-API. Bei Überschreitung gibt die API HTTP 429 Too Many Requests mit einem Retry-After-Header zurück.

Wie erstelle ich eine Mission und füge Datenpakete über die API hinzu?

Die Missionserstellung ist ein zweistufiger Prozess: zuerst POST an /api/mission mit Name, Beschreibung und optionaler Gruppenzuweisung, um eine Mission-UID zurückzuerhalten. Dann POST an /api/mission/{uid}/attachment mit einem multipart/form-data-Body mit der Datenpaket-Datei (MBTiles, KMZ oder GeoJSON).

Kann ich MBTiles-Kartenebenen über die CloudTAK API hochladen?

Ja. POST an /api/layer mit einem multipart/form-data-Body mit der MBTiles-Datei und Metadaten (name, minZoom, maxZoom, bounds). CloudTAK validiert das MBTiles-Format und macht die Ebene für alle verbundenen Clients verfügbar. PMTiles wird ebenfalls über denselben Endpunkt unterstützt.

Wie funktionieren Webhooks in CloudTAK?

CloudTAK-Webhooks werden über POST /api/webhook mit einer Ziel-URL, Event-Typen und einem optionalen HMAC-Geheimnis für Payload-Signierung registriert. Bei Lieferfehlern wiederholt CloudTAK mit exponentiellem Backoff bis zu 5 Mal.

Wie verwendet TAKpilot die CloudTAK API zur Ausführung von natürlichsprachlichen Befehlen?

TAKpilot empfängt natürlichsprachliche Befehle von Operatoren und zerlegt sie in CloudTAK-API-Aufrufe. Ein Befehl zum Markieren einer Position wird zu POST /api/cot mit dem entsprechenden CoT-Typ. TAKpilot pflegt einen Sitzungskontext, sodass Folgeanfragen Referenzen aus vorherigen API-Antworten auflösen. Es nutzt auch den WebSocket-Stream reaktiv.

Welche Event-Typen kann ich über den CloudTAK WebSocket abonnieren?

Der CloudTAK WebSocket-Stream emittiert fünf Event-Typen: cot (ein CoT-XML-Event), track_update (ein Delta-Update der Position eines bestehenden Tracks), mission_update (eine Mission wurde erstellt, geändert oder gelöscht), user_event (ein Client hat verbunden, getrennt oder Rufzeichen/Team geändert) und system_event (serverseitige Events). Abonnieren Sie selektiv mit dem types-Filterfeld.

Wie versioniere ich Datenpakete, die an Missionen angehängt sind?

CloudTAK führt eine Versionshistorie für jeden Datenpaket-Anhang. Jeder Upload an /api/mission/{uid}/attachment erstellt eine neue Version. Die aktuelle (neueste) Version wird standardmäßig bereitgestellt. Um eine bestimmte Version abzurufen, fügen Sie den Abfrageparameter version hinzu: GET /api/mission/{uid}/attachment/{attachmentId}?version=2.