NIGHTHAWK API v2.0

Defense aerospace intelligence API. Query military aircraft production forecasts, live GDELT global events, and AI-powered defense briefs.

🔐 Get Your API Key

Generate a free API key to start querying the NIGHTHAWK API. No credit card required for the Free tier.

Pricing

Annual billing saves ~2 months. Pro yearly $490 · Enterprise yearly $4,990

Base URL

https://nighthawk-api.ml-nightworx.io

Authentication

All API requests require a Bearer token. Get your key above.

Authorization: Bearer nhwk_your_api_key_here

Rate Limits

Tier	Requests/day	Requests/min	Cost
Free	100	10	$0
Pro	10,000	100	$49/mo
Enterprise	Unlimited	1,000	$499/mo

Rate limit info is returned in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-Credits-Tier. On 429, check Retry-After.

Endpoints

GET /feeds/events

Live GDELT global events from the past 24 hours.

Parameter	Type	Default	Description
limit	integer	20	Max 100
category	string	—	Battles, Protests, Political, Economic
country	string	—	Country name (e.g., Ukraine, China)

curl "https://nighthawk-api.ml-nightworx.io/feeds/events?category=Battles&limit=10" \
  -H "Authorization: Bearer nhwk_YOUR_KEY"

GET /feeds/stories

Clustered news stories with metadata.

curl "https://nighthawk-api.ml-nightworx.io/feeds/stories?limit=10" \
  -H "Authorization: Bearer nhwk_YOUR_KEY"

GET /feeds/entities

People, organizations, and locations extracted from global coverage.

curl "https://nighthawk-api.ml-nightworx.io/feeds/entities?limit=10" \
  -H "Authorization: Bearer nhwk_YOUR_KEY"

GET /feeds/defense-brief

Combined brief: HAWK1 production metrics + GDELT live events + capability gap analysis. AI-ready synthesis.

curl "https://nighthawk-api.ml-nightworx.io/feeds/defense-brief" \
  -H "Authorization: Bearer nhwk_YOUR_KEY"

POST /chat

Ask NIGHTHAWK a question in natural language. Powered by Google Gemini. Pro tier or higher required.

Parameter	Type	Required	Description
prompt	string	Yes	Your question about the defense data
model	string	No	gemini-2.5-flash (default) or gemini-2.5-pro

curl -X POST "https://nighthawk-api.ml-nightworx.io/chat" \
  -H "Authorization: Bearer nhwk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"What is the biggest capability gap?"}'

POST /api/keys/create

Programmatically generate a new API key. No auth required.

curl -X POST "https://nighthawk-api.ml-nightworx.io/api/keys/create" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","tier":"free","label":"my-agent"}'

GET /api/keys/verify

Check key status and tier. Include the key as Bearer token.

curl "https://nighthawk-api.ml-nightworx.io/api/keys/verify" \
  -H "Authorization: Bearer nhwk_YOUR_KEY"

GET /health

Service health check. No auth required.

curl "https://nighthawk-api.ml-nightworx.io/health"

Response Format

All responses are JSON. Event objects contain:

{
  "id": "conflict_9919de1954eb7de1",
  "title": "Russians leave Malian soldiers trapped...",
  "event_date": "2026-07-31",
  "category": "Battles",
  "subcategory": "Armed clash",
  "geo": {
    "country": "Mali",
    "region": "Western Africa",
    "latitude": 16.27,
    "longitude": -0.04
  },
  "fatalities": 60,
  "metrics": {
    "significance": 0.79,
    "severity_tier": "critical",
    "confidence": 0.78
  }
}

Errors

Code	Meaning
200	Success
401	Unauthorized — invalid or missing API key
429	Rate limit exceeded — check Retry-After header
502	Upstream error (GDELT or Gemini unavailable)

SDK Examples

Python

import requests

API_KEY = "nhwk_YOUR_KEY"
BASE = "https://nighthawk-api.ml-nightworx.io"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Get defense brief
resp = requests.get(f"{BASE}/feeds/defense-brief", headers=headers)
brief = resp.json()
print(f"${brief['hawk1_summary']['total_market_value_b']}B market")
print(f"{brief['gdelt_live']['battle_events_24h']} battle events today")

# Ask AI
resp = requests.post(f"{BASE}/chat", headers=headers,
    json={"prompt": "Compare NATO vs China production"})
print(resp.json()["response"])

JavaScript

const BASE = "https://nighthawk-api.ml-nightworx.io";
const KEY = "nhwk_YOUR_KEY";
const headers = {"Authorization": `Bearer ${KEY}`, "Content-Type": "application/json"};

// Get events
const events = await fetch(`${BASE}/feeds/events?limit=5`, {headers}).then(r => r.json());

// Chat
const chat = await fetch(`${BASE}/chat`, {
  method: "POST", headers,
  body: JSON.stringify({prompt: "Which programs are sunsetting?"})
}).then(r => r.json());
console.log(chat.response);

Agent Self-Registration (Python)

import requests

# 1. Create a free API key
resp = requests.post("https://nighthawk-api.ml-nightworx.io/api/keys/create",
    json={"email": "[email protected]", "tier": "free", "label": "prod-agent-1"})
api_key = resp.json()["api_key"]

# 2. Use the API
headers = {"Authorization": f"Bearer {api_key}"}
events = requests.get("https://nighthawk-api.ml-nightworx.io/feeds/events?limit=5",
    headers=headers).json()

# 3. Upgrade via Stripe when ready
# POST /api/stripe/checkout with {"price_id": "pro_monthly", "email": "...", "api_key": "..."}

Agent Micropayments LIVE

AI agents can autonomously pay for NIGHTHAWK API calls using USDC on Base. No gas per request — agents sign an off-chain message per call, and the backend deducts from an internal credit balance. On-chain settlement only happens on deposit.

How It Works

1. Register — POST /api/agent/register with your wallet address
2. Deposit — Send USDC (Base) to the treasury address, then POST /api/agent/deposit with the tx hash
3. Call — Sign each API request with your wallet. Backend verifies the EVM signature and deducts $0.01 per call
4. Monitor — GET /api/agent/balance to check remaining credits

POST /api/agent/register

Register a new agent with your EVM wallet address. Returns an agent_id and auth instructions.

curl -X POST "https://nighthawk-api.ml-nightworx.io/api/agent/register" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0xYourWallet","label":"my-agent","email":"[email protected]"}'

POST /api/agent/deposit

After sending USDC (Base) to the treasury, submit the tx hash to credit your agent balance. Backend verifies the on-chain transfer.

curl -X POST "https://nighthawk-api.ml-nightworx.io/api/agent/deposit" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0xYourWallet","tx_hash":"0xTxHash"}'

GET /api/agent/balance

Check your agent's credit balance and usage stats.

curl "https://nighthawk-api.ml-nightworx.io/api/agent/balance?wallet_address=0xYourWallet"

Agent Authenticated API Calls

Instead of Authorization: Bearer, agents use EVM signed headers:

Header	Description
X-Agent-Address	Your EVM wallet address (0x...)
X-Agent-Nonce	Random hex string (unique per request)
X-Agent-Signature	EIP-191 personal_sign of nighthawk:<path>:<nonce>

The message to sign is: nighthawk:/feeds/defense-brief:yourNonce123

# Python agent example
from eth_account import Account
from web3 import Web3
import requests, secrets

agent = Account.from_key("your_private_key")
nonce = secrets.token_hex(16)
path = "/feeds/defense-brief"
message = f"nighthawk:{path}:{nonce}"
signature = agent.sign_message(message.encode()).signature.hex()

resp = requests.get(f"https://nighthawk-api.ml-nightworx.io{path}", headers={
    "X-Agent-Address": agent.address,
    "X-Agent-Nonce": nonce,
    "X-Agent-Signature": signature,
})
print(resp.json())
# $0.01 deducted from your agent balance automatically