API Documentation

FoxIO 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://ja4-atlas.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://ja4-atlas.platphormnews.com/api/ingest/http \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "ts": 1767819390662,
    "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://ja4-atlas.platphormnews.com/api/lookup?fingerprint=t13d1517h2_8daaf6152771_b0da82dd1658"

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

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

curl -X POST https://ja4-atlas.platphormnews.com/api/ingest/http \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{ "ts": 1767819390662, "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" }