CloudTAK REST API integratie: externe systemen verbinden met uw tactisch netwerk

Door Corvus Intelligence Engineering Team · Over het team →

29 mei 2026 12 min lezen

De REST API van CloudTAK verandert een TAK-server van een passief doorstuurpunt in een actieve integratieHub. In plaats van elke gegevensbron te vereisen native CoT via TCP/TLS te spreken — het enige pad naar de legacy TAK Server — biedt CloudTAK een volledig HTTP- en WebSocket-oppervlak dat elk modern systeem kan aanroepen: sensorarrays, logistieke platforms, AI-inferentiepijplijnen, SIGINT-feeds en aangepaste dashboards. Deze gids behandelt alle belangrijke API-oppervlakken in detail: authenticatie, CoT-injectie, realtime track-streaming, missiebeheer, datapakketupload, groepsbeheer, webhooks en de TAKpilot AI-copiloot als integratievoorbeeld. Als u eerst een CloudTAK-server moet opzetten, raadpleeg dan onze handleiding voor CloudTAK-serverimplementatie.

Authenticatie: JWT-tokens, API-sleutels en bereiken

De CloudTAK REST API dwingt authenticatie af op elk eindpunt behalve de gezondheidscheck (GET /api/health). Twee referentietypen worden ondersteund, beide doorgegeven als HTTP-header Authorization: Bearer <token>.

JWT-tokens

JWT-tokens zijn kortlevend en worden per gebruikerssessie uitgegeven. Verkrijg er een door inloggegevens naar het inlogeindpunt te sturen:

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'

De standaard TTL is 86400 seconden (24 uur); configureerbaar via CLOUDTAK_JWT_TTL. JWT's bevatten de rol van de gebruiker en groepslidmaatschappen als claims, zodat toestemmingscontroles stateless zijn.

API-sleutels

API-sleutels zijn langlevende tokens voor geautomatiseerde service-naar-service-integraties. Genereer ze via de beheer-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'

Ondersteunde bereiken en waartoe ze toegang verlenen:

Bereik	Verleent toegang tot
`cot:write`	CoT-events injecteren via POST /api/cot
`cot:read`	Historische tracks opvragen via GET /api/cot
`events:subscribe`	Verbinding met de WebSocket-stroom op /api/ws
`mission:write`	Missies aanmaken, bijwerken en verwijderen
`package:write`	Datapakketten en bijlagen uploaden
`group:write`	Groepen aanmaken en lidmaatschap beheren
`admin`	Alle bereiken plus gebruikersbeheer en serverconfiguratie

Revoceer een sleutel op elk moment: DELETE /api/token/{id}. Actieve sleutels weergeven: GET /api/token.

Basis-URL en snelheidslimieten

Alle REST-eindpunten worden aangeboden onder https://<host>:8443/api/. De standaard globale snelheidslimiet is 100 verzoeken per seconde per API-sleutel. HTTP 429-reacties bevatten een Retry-After-header. De OpenAPI-specificatie is beschikbaar op GET /api/docs.

CoT-injectie: POST /api/cot

Het CoT-injectie-eindpunt is het primaire pad voor het pushen van positierapporten, contactmarkers, alerts en andere CoT-events in het tactische beeld vanuit externe systemen. Het accepteert zowel rauwe CoT XML als een handig JSON-formaat.

XML-payload

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>Grondradar contact, snelheid 12 kph, koers 045</remarks>
    <group name="Surveillance" role="Team Member"/>
  </detail>
</event>'

JSON-payload

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": "Bevoorradingskonvooi, ETA checkpoint 14:45Z",
    "group": "Logistics",
    "role": "Team Member"
  }'

CloudTAK serialiseert deze JSON intern naar een volledige CoT XML-envelop. Een succesvolle injectie retourneert HTTP 201. Het event verspreidt zich onmiddellijk naar alle geabonneerde clients en de WebSocket-stroom.

Track-streaming: WebSocket /api/ws

Voor realtime consumptie van het tactische beeld biedt het WebSocket-eindpunt een continue, lage-latentie stroom van CoT-events.

Verbinden en abonneren

// Node.js-voorbeeld met de 'ws'-bibliotheek
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} op ${event.payload.lat},${event.payload.lon}`);
  } else if (event.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }));
  }
});

De server stuurt elke 30 seconden een ping-bericht. Clients moeten binnen 10 seconden reageren met pong of de verbinding wordt gesloten.

Missie-API: aanmaken, bijwerken, verwijderen en toewijzen

Missies in CloudTAK zijn benoemde operationele contexten die tracks, datapakketten en gebruikers groeperen. De missie-API stelt externe systemen in staat om programmatisch missies aan te maken.

Een missie aanmaken

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

Het antwoord bevat de missie-uid (een UUID). Metadata bijwerken: PATCH /api/mission/{uid}. Verwijderen: DELETE /api/mission/{uid}.

Datapakket-API: MBTiles, KMZ, GeoJSON en versiebeheer

# MBTiles-laag uploaden voor offline-kaartdekking
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=Sector Noord basiskaart" \
  -F "contentType=application/vnd.mbtiles" \
  | jq '{attachmentId: .id, version: .version}'

Zelfstandige kaartlagen worden geüpload via POST /api/layer. Voor offline-first implementaties: MBTiles en PMTiles voor offline kaarten.

Groepen en kanalen: zichtbaarheidsfiltering en track-toegangsbeheer

CloudTAK-groepen implementeren track-zichtbaarheidssegregatie. Een track met een groepstag is alleen zichtbaar voor verbonden clients die lid zijn van die groep. Dit maakt need-to-know-scheiding mogelijk binnen een gedeelde TAK-server.

Een groep aanmaken en gebruikers toewijzen

# Groep aanmaken
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": "Inlichtingen, Surveillance, Verkenningscel"}' \
  | jq '.id'

# Gebruiker toevoegen aan groep
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"}'

Een client kan simultaan lid zijn van meerdere groepen. Tracks zonder groepstag zijn zichtbaar voor alle gebruikers op de server.

TAKpilot als integratievoorbeeld

TAKpilot is de AI-copiloot van Corvus Intelligence voor TAK-gebaseerde operaties. Het is een concreet voorbeeld van diepe CloudTAK API-integratie: TAKpilot abonneert op de WebSocket-trackstroom, verwerkt natuurlijke taalcommando's van operators en voert ze uit als CloudTAK API-aanroepen.

Een opdracht in natuurlijke taal zoals "markeer raster 38T YQ 45123 67890 als vijandelijk contact, wijs toe aan Alpha-Company-missie" triggert de volgende API-sequentie in TAKpilot:

MGRS 38T YQ 45123 67890 converteren naar decimale graden (interne conversie, geen API-aanroep).
POST /api/cot met type a-h-G (vijandelijk grond) en de geconverteerde coördinaten.
GET /api/mission?name=Alpha-Company om de missie-UID op te lossen.
POST /api/mission/{uid}/cot om de geïnjecteerde CoT-event UID aan de missie te koppelen.
Antwoord aan de operator via de TAKpilot-chatinterface met bevestiging van de actie.

Webhooks: abonneren op events en doorsturen naar externe systemen

Webhooks stellen CloudTAK in staat events naar externe systemen te pushen in plaats van die systemen de REST API te laten pollen of een persistente WebSocket-verbinding te laten onderhouden.

Een webhook registreren

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 ondertekent elke webhook-levering met een HMAC-SHA256-handtekening in de X-CloudTAK-Signature-header. Verifieer de handtekening aan de ontvangerkant:

// Express.js webhook-ontvanger met handtekeningverificatie
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('Handtekening komt niet overeen');
  }

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

Leveringsfouten triggeren nieuwe pogingen met exponentiële backoff: 1, 2, 4, 8, 16 seconden. Leveringsgeschiedenis bekijken: GET /api/webhook/{id}/deliveries.

Ondersteunde webhook-eventtypen

new_track — een nieuwe UID verschijnt voor het eerst op het beeld.
track_stale — de veroudertimestamp van een track is verstreken zonder update.
mission_update — een missie is aangemaakt, gewijzigd, gearchiveerd of verwijderd.
user_join — een nieuwe client heeft verbinding gemaakt en is geauthenticeerd.
user_leave — een client heeft de verbinding verbroken of de sessie is verlopen.
cot_alert — een CoT-event met het type-prefix b-a (alarm) is ontvangen.

Verbind uw systemen met het TAK-ecosysteem

Wij bouwen CloudTAK API-integraties voor sensornetwerken, logistieke platforms, AI-inferentiepijplijnen en aangepaste C2-dashboards — en we ondersteunen ze met TAKpilot, onze AI-copiloot voor tactische operaties.

TAKpilot AI-copiloot → Briefing boeken

Deze analyse is opgesteld door Corvus Intelligence-ingenieurs die bedrijfskritische software bouwen voor defensie- en overheidsorganisaties. Meer over ons team →

Veelgestelde vragen

Welke authenticatiemethoden ondersteunt de CloudTAK REST API?

De CloudTAK REST API ondersteunt twee authenticatiemethoden: JWT bearer-tokens en statische API-sleutels. JWT-tokens worden uitgegeven via POST /api/login en verlopen na een configureerbare TTL (standaard 24 uur). API-sleutels zijn langlevende tokens gegenereerd via de beheer-API, geschikt voor service-naar-service-integraties.

Wat is het juiste Content-Type voor CoT-injectie via de REST API?

Het CloudTAK CoT-injectie-eindpunt (POST /api/cot) accepteert twee inhoudstypen: application/xml voor rauwe CoT XML-payloads en application/json voor een JSON-wrapper die CloudTAK intern converteert naar CoT XML. Neem altijd de Content-Type-header expliciet op.

Hoe filter ik de WebSocket-trackstroom naar een specifieke groep of begrensd gebied?

Het CloudTAK WebSocket-eindpunt (/api/ws) accepteert een abonnementfilterobject bij verbinding. Het filter ondersteunt drie velden: groups (array van groepsnamen), bbox (GeoJSON begrenzingskader [minLon, minLat, maxLon, maxLat]) en types (array van CoT-type-strings). U kunt filters bijwerken op een actieve verbinding.

Wat is de snelheidslimiet op het CoT-injectie-eindpunt?

De standaard CloudTAK-snelheidslimiet is 100 CoT-events per seconde per API-sleutel. Configureerbaar via de omgevingsvariabele CLOUDTAK_COT_RATE_LIMIT of per sleutel via de beheer-API. Als uw integratie de limiet overschrijdt, retourneert de API HTTP 429 Too Many Requests met een Retry-After-header.

Hoe maak ik een missie aan en voeg ik datapakketten toe via de API?

Het aanmaken van een missie is een tweestapig proces: eerst POST naar /api/mission met een naam, beschrijving en optionele groepstoewijzing om een missie-UID terug te krijgen. Vervolgens POST naar /api/mission/{uid}/attachment met een multipart/form-data-body met het datapakketbestand (MBTiles, KMZ of GeoJSON).

Kan ik MBTiles-kaartlagen uploaden via de CloudTAK API?

Ja. POST naar /api/layer met een multipart/form-data-body met het MBTiles-bestand en metadata (name, minZoom, maxZoom, bounds). CloudTAK valideert het MBTiles-formaat en maakt de laag beschikbaar voor alle verbonden clients. PMTiles wordt ook ondersteund via hetzelfde eindpunt.

Hoe werken webhooks in CloudTAK?

CloudTAK-webhooks worden geregistreerd via POST /api/webhook met een doel-URL, eventtypen en een optioneel HMAC-geheim voor payload-ondertekening. Bij leveringsfouten probeert CloudTAK het opnieuw met exponentiële backoff tot 5 keer.

Hoe gebruikt TAKpilot de CloudTAK API om opdrachten in natuurlijke taal uit te voeren?

TAKpilot ontvangt opdrachten in natuurlijke taal van operators en ontleedt deze in CloudTAK API-aanroepen. Een opdracht om een locatie te markeren wordt een POST /api/cot met het juiste CoT-type. TAKpilot handhaaft een sessiecontext en verbruikt de WebSocket-stroom ook reactief.

Op welke eventtypen kan ik abonneren via de CloudTAK WebSocket?

De CloudTAK WebSocket-stroom zendt vijf eventtypen uit: cot (een CoT XML-event), track_update (een delta-update van een bestaand track), mission_update (een missie is aangemaakt, gewijzigd of verwijderd), user_event (een client verbond, ontkoppelde of veranderde roepnaam/team) en system_event (server-side events). Abonneer selectief met het filterveld types.

Hoe beheer ik versies van datapakketten die aan missies zijn gekoppeld?

CloudTAK houdt een versiegeschiedenis bij voor elke datapakketbijlage. Elke upload naar /api/mission/{uid}/attachment maakt een nieuwe versie. De huidige (nieuwste) versie wordt standaard bediend. Om een specifieke versie op te halen, voeg de versie-queryparameter toe: GET /api/mission/{uid}/attachment/{attachmentId}?version=2.