vNAS → VATSWIM Push Integration

This document describes how vNAS (Virtual National Airspace System) can push ATC automation data to PERTI's VATSWIM API.

Overview

PERTI receives ATC automation data from vNAS to update track surveillance, automation tags, handoff state, and metering data for flights on the VATSIM network. This enables real-time coordination between vNAS ERAM/STARS systems and the PERTI SWIM platform.

Endpoints

Authentication

Use the Authorization header with a Bearer token:

Authorization: Bearer swim_sys_vnas_zdc_a1b2c3d4e5f6

Alternative: Use the X-API-Key header if Bearer tokens are inconvenient:

X-API-Key: swim_sys_vnas_zdc_a1b2c3d4e5f6

Rate Limits

• 30,000 requests per minute (system tier)
• Track data: up to 1,000 tracks per request
• Tags data: up to 500 tags per request
• Handoff data: up to 200 handoffs per request

Track/Surveillance Data

Endpoint

POST /api/swim/v1/ingest/vnas/track

Request Format

{
  "facility_id": "ZDC",
  "system_type": "ERAM",
  "timestamp": "2026-01-27T15:30:00.000Z",
  "tracks": [
    {
      "callsign": "UAL123",
      "gufi": "VAT-20260127-UAL123-KORD-KJFK",
      "beacon_code": "1234",
      "position": {
        "latitude": 40.6413,
        "longitude": -73.7781,
        "altitude_ft": 35000,
        "altitude_type": "barometric",
        "ground_speed_kts": 450,
        "track_deg": 270,
        "vertical_rate_fpm": -500
      },
      "track_quality": {
        "source": "radar",
        "mode_c": true,
        "mode_s": true,
        "ads_b": false,
        "position_quality": 9
      },
      "timestamp": "2026-01-27T15:30:00.000Z"
    }
  ]
}

Field Reference

Automation Tags

Endpoint

POST /api/swim/v1/ingest/vnas/tags

Request Format

{
  "facility_id": "ZDC",
  "system_type": "ERAM",
  "tags": [
    {
      "callsign": "UAL123",
      "gufi": "VAT-20260127-UAL123-KORD-KJFK",
      "assigned_altitude": 35000,
      "interim_altitude": 28000,
      "assigned_speed": 280,
      "assigned_heading": 270,
      "scratchpad": "KJFK/31L",
      "scratchpad2": "GDP+15",
      "point_out_sector": "33",
      "coordination_status": "TRACKED",
      "conflict_alert": false,
      "msaw_alert": false,
      "timestamp": "2026-01-27T15:30:00Z"
    }
  ]
}

Field Reference

Handoff Data

Endpoint

POST /api/swim/v1/ingest/vnas/handoff

Request Format

{
  "facility_id": "ZDC",
  "handoffs": [
    {
      "callsign": "UAL123",
      "gufi": "VAT-20260127-UAL123-KORD-KJFK",
      "handoff_type": "AUTOMATED",
      "from_sector": "ZDC_33_CTR",
      "to_sector": "ZNY_42_CTR",
      "from_facility": "ZDC",
      "to_facility": "ZNY",
      "status": "INITIATED",
      "initiated_at": "2026-01-27T15:30:00Z",
      "accepted_at": null,
      "boundary_fix": "SWANN"
    }
  ]
}

Field Reference

Response Format

Success Response (HTTP 200)

{
  "success": true,
  "data": {
    "processed": 50,
    "updated": 48,
    "not_found": 2,
    "errors": 0,
    "error_details": []
  },
  "meta": {
    "source": "vnas",
    "facility": "ZDC",
    "system": "ERAM",
    "batch_size": 50
  },
  "timestamp": "2026-01-27T15:30:00Z"
}

Error Codes

Example cURL Requests

Track Update

curl -X POST https://perti.vatcscc.org/api/swim/v1/ingest/vnas/track \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer swim_sys_vnas_zdc_a1b2c3d4e5f6" \
  -d '{
    "facility_id": "ZDC",
    "system_type": "ERAM",
    "tracks": [{
      "callsign": "UAL123",
      "beacon_code": "4521",
      "position": {
        "latitude": 39.8561,
        "longitude": -77.0369,
        "altitude_ft": 35000,
        "ground_speed_kts": 485
      },
      "track_quality": {
        "mode_c": true,
        "mode_s": true,
        "position_quality": 9
      }
    }]
  }'

Tags Update

curl -X POST https://perti.vatcscc.org/api/swim/v1/ingest/vnas/tags \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer swim_sys_vnas_zdc_a1b2c3d4e5f6" \
  -d '{
    "facility_id": "ZDC",
    "system_type": "ERAM",
    "tags": [{
      "callsign": "UAL123",
      "assigned_altitude": 35000,
      "assigned_speed": 280,
      "scratchpad": "KJFK/31L",
      "coordination_status": "TRACKED"
    }]
  }'

Handoff Update

curl -X POST https://perti.vatcscc.org/api/swim/v1/ingest/vnas/handoff \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer swim_sys_vnas_zdc_a1b2c3d4e5f6" \
  -d '{
    "facility_id": "ZDC",
    "handoffs": [{
      "callsign": "UAL123",
      "handoff_type": "AUTOMATED",
      "from_sector": "ZDC_33_CTR",
      "to_sector": "ZNY_42_CTR",
      "status": "INITIATED",
      "initiated_at": "2026-01-27T15:30:00Z",
      "boundary_fix": "SWANN"
    }]
  }'

Data Authority

vNAS has priority 1 for track data in VATSWIM. This means:

• vNAS track updates will override data from lower-priority sources
• Track quality and beacon code from vNAS are considered authoritative

Document version: 1.0.0 | Last updated: 2026-01-27