API Documentation

Platphorm Atlas API v0.1.0

Overview

The Vercel Sentinel API provides programmatic access to JA4 fingerprint intelligence. Use these endpoints to ingest observations from your sensors, lookup fingerprints, and query threat campaigns.

Base URL

https://atlas.platphormnews.com

Network Graph: https://platphormnews.com/api/network/graph

Platphorm Docs: https://platphormnews.com/api/docs

Claws Integration: https://claws.platphormnews.com

Authentication

Write endpoints require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

Quick Start - Ingest Example

curl -X POST https://atlas.platphormnews.com/api/ingest/http \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "ts": 1775242587408,
    "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658",
    "sensor": "my-sensor",
    "env": "production",
    "path": "/api/test",
    "method": "GET",
    "ip": "203.0.113.42"
  }'

Quick Start - Lookup Example

curl "https://atlas.platphormnews.com/api/lookup?fingerprint=t13d1517h2_8daaf6152771_b0da82dd1658"

Quick Start - Health Check Example

curl "https://atlas.platphormnews.com/api/health"

Claws Integration

Leverage claws.platphormnews.com for advanced network intelligence and automated threat correlation.

post/api/ingest/http

Ingest JA4 observation

Ingests a single JA4 fingerprint observation from a sensor. This endpoint is designed for: - Vercel Firewall middleware integration - Zeek network sensors - Custom WAF implementations - Any system that can extract JA4 fingerprints The observation will be stored and correlated with existing fingerprint data.

Example Request

From Vercel Middleware

{
  "ts": 1733260800000,
  "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658",
  "ja3": null,
  "sensor": "myapp-prod",
  "env": "production",
  "projectId": "prj_xxxxxxxxxxxx",
  "projectUrl": "myapp.vercel.app",
  "vercelRegion": "iad1",
  "path": "/api/users",
  "method": "GET",
  "ip": "203.0.113.42"
}

From Zeek Sensor

{
  "ts": 1733260800000,
  "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658",
  "ja4s": "t120300_c02b_a56c0d24d0a9",
  "sensor": "zeek-lab-1",
  "env": "lab",
  "ip": "10.0.1.50"
}

Responses

200Observation ingested successfully

401Missing or invalid authorization header

403Invalid token

500Internal server error

post/api/ingest/zeek

Ingest Zeek SSL/TLS logs

Ingest JA4 fingerprint observations from Zeek network sensors. Accepts Zeek ssl.log JSON format (either a single record or wrapped in a logs array). Timestamps may be epoch floats (Zeek native) or ISO-8601 strings.

Example Request

Zeek ssl.log batch

{
  "sensor": "zeek-prod-1",
  "log_type": "ssl",
  "logs": [
    {
      "ts": 1733260800,
      "uid": "CXKd3f1pXP5lMcHS5g",
      "id.orig_h": "192.168.1.100",
      "id.orig_p": 54321,
      "id.resp_h": "93.184.216.34",
      "id.resp_p": 443,
      "version": "TLSv13",
      "cipher": "TLS_AES_128_GCM_SHA256",
      "server_name": "example.com",
      "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658",
      "established": true
    }
  ]
}

Responses

200Logs ingested successfully

400Invalid payload

401Unauthorized

post/api/ingest/suricata

Ingest Suricata EVE JSON logs

Ingest JA4 fingerprint observations from Suricata IDS/IPS sensors. Accepts both standard JSON (with `events` array) and newline-delimited EVE JSON (`application/x-ndjson`). Only TLS events with JA4 data are processed.

Example Request

Suricata EVE JSON TLS event

{
  "sensor": "suricata-edge-1",
  "events": [
    {
      "timestamp": "2024-01-15T10:30:00.123456+0000",
      "event_type": "tls",
      "src_ip": "192.168.1.100",
      "src_port": 54321,
      "dest_ip": "93.184.216.34",
      "dest_port": 443,
      "tls": {
        "version": "TLS 1.3",
        "sni": "example.com",
        "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658"
      }
    }
  ]
}

Responses

200Events ingested

400Invalid payload

401Unauthorized

post/api/ingest/batch

Batch ingest observations

Ingest multiple JA4 fingerprint observations in a single request. Supports JSON, CSV, and NDJSON formats. Maximum batch size is configurable (default 1000 records). Optional deduplication flag removes duplicate fingerprints.

Example Request

JSON batch

{
  "format": "json",
  "source": "my-scanner",
  "deduplicate": true,
  "records": [
    {
      "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658",
      "src_ip": "192.168.1.100",
      "sensor": "lab-sensor",
      "ts": 1733260800000
    }
  ]
}

Responses

200Batch processed

400Invalid payload or batch too large

401Unauthorized

get/api/lookup

Lookup fingerprint

Lookup detailed information about a JA4 fingerprint. Returns: - Internal fingerprint data (label, severity, notes) - JA4DB enrichment (application, OS, category) - Observation statistics (total hits, first/last seen, unique IPs/sensors) - Recent observations - Associated threat campaigns

Parameters

fingerprint(query)required- JA4 fingerprint value to lookup

Responses

200Fingerprint data retrieved

400Missing fingerprint parameter

post/api/fingerprints/label

Label fingerprint

Add or update label, severity, and notes for a fingerprint.

Responses

200Fingerprint labeled successfully

get/api/stats

Get dashboard statistics

Returns overall platform statistics for the dashboard.

Responses

200Statistics retrieved

get/api/observations

List observations

Returns paginated list of raw observations from all sensors.

Parameters

page(query)- Page number (1-indexed)

limit(query)- Results per page

sensor(query)- Filter by sensor name

ja4(query)- Filter by JA4 fingerprint

Responses

200Observations retrieved

get/api/campaigns

List campaigns

Returns all threat campaigns with their associated fingerprints.

Responses

200Campaigns retrieved

get/api/infrastructure

List infrastructure

Returns tracked infrastructure (IPs, domains, ASNs, etc.).

Parameters

kind(query)- Filter by infrastructure type

Responses

200Infrastructure retrieved

get/api/health

Health check

Returns system health status including database connectivity.

Responses

200System healthy

503System unhealthy

get/api/projects

List projects

Returns all monitored Vercel projects with real-time statistics. Each project includes: - Total observations and unique fingerprints - Activity metrics (24h, 1h) - Threat indicators (critical, high counts) - Last seen timestamp

Responses

200Projects retrieved successfully

post/api/projects

Add project

Add a new Vercel project to monitor for JA4 fingerprint observations. The project_id must be a valid Vercel project ID (starts with 'prj_'). Once added, all observations from this project will be automatically correlated.

Responses

201Project created successfully

400Invalid request

409Project ID already exists

get/api/projects/{id}

Get project details

Returns detailed statistics for a specific project.

Parameters

id(path)required- Project database ID

Responses

200Project retrieved

404Project not found

patch/api/projects/{id}

Update project

Update project name, description, environment, or status.

Parameters

id(path)required- Project database ID

Responses

200Project updated

404Project not found

delete/api/projects/{id}

Delete project

Remove a project from monitoring. Observations are not deleted.

Parameters

id(path)required- Project database ID

Responses

200Project deleted

404Project not found

post/api/projects/validate

Validate project ID

Validate Vercel project ID format before adding.

Responses

200Validation result

get/api/sensors

List sensors

Returns all registered sensors with their last-seen timestamps and observation counts.

Responses

200Sensors retrieved

get/api/alerts

List alerts

Returns security alerts with optional filtering by status and severity.

Parameters

status(query)- Filter by alert status

severity(query)- Filter by severity

limit(query)- Maximum number of alerts to return

Responses

200Alerts retrieved

post/api/alerts

Create alert

Create a new security alert.

Responses

201Alert created

401Unauthorized

get/api/alerts/feed

Real-time alert feed

Returns the latest alerts for real-time dashboard display, sorted by creation time descending.

Responses

200Alert feed retrieved

get/api/actors

List threat actors

Returns all tracked threat actors with associated campaigns and fingerprints.

Responses

200Actors retrieved

post/api/actors

Create threat actor

Add a new threat actor to track.

Responses

201Actor created

401Unauthorized

get/api/actors/{id}

Get actor details

Returns detailed information about a specific threat actor including linked campaigns.

Parameters

id(path)required- Actor ID

Responses

200Actor retrieved

404Actor not found

get/api/firewall/rules

List firewall rules

Returns all configured firewall rules for automated blocking based on JA4 fingerprints.

Responses

200Firewall rules retrieved

post/api/firewall/rules

Create firewall rule

Create a new rule to block or flag traffic matching a JA4 fingerprint pattern.

Responses

201Rule created

401Unauthorized

curl -X POST https://atlas.platphormnews.com/api/ingest/http \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{ "ts": 1775242587408, "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658", "sensor": "my-sensor", "env": "production", "path": "/api/test", "method": "GET", "ip": "203.0.113.42" }'

{ "ts": 1733260800000, "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658", "ja3": null, "sensor": "myapp-prod", "env": "production", "projectId": "prj_xxxxxxxxxxxx", "projectUrl": "myapp.vercel.app", "vercelRegion": "iad1", "path": "/api/users", "method": "GET", "ip": "203.0.113.42" }

{ "sensor": "zeek-prod-1", "log_type": "ssl", "logs": [ { "ts": 1733260800, "uid": "CXKd3f1pXP5lMcHS5g", "id.orig_h": "192.168.1.100", "id.orig_p": 54321, "id.resp_h": "93.184.216.34", "id.resp_p": 443, "version": "TLSv13", "cipher": "TLS_AES_128_GCM_SHA256", "server_name": "example.com", "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658", "established": true } ] }

{ "sensor": "suricata-edge-1", "events": [ { "timestamp": "2024-01-15T10:30:00.123456+0000", "event_type": "tls", "src_ip": "192.168.1.100", "src_port": 54321, "dest_ip": "93.184.216.34", "dest_port": 443, "tls": { "version": "TLS 1.3", "sni": "example.com", "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658" } } ] }

{ "format": "json", "source": "my-scanner", "deduplicate": true, "records": [ { "ja4": "t13d1517h2_8daaf6152771_b0da82dd1658", "src_ip": "192.168.1.100", "sensor": "lab-sensor", "ts": 1733260800000 } ] }