API Documentation — ThreatChain

Authentication

All API requests require a tck_ prefixed API key sent via the Authorization header:

Authorization: Bearer tck_your_api_key_here

Get your API key from the Customer Portal or request one when you sign up.

Endpoints

Public (No Auth)

GET /health

Chain health status, active threat count, node connections.

Threats

POST /api/v1/threats

Add a new threat to the blockchain. Requires: target (IP/CIDR). Optional: source, category, severity, action, ttl_seconds.

GET /api/v1/threats

List threats. Query params: count, target, action, severity, active_only.

GET /api/v1/threats/{threat_id}

Get a specific threat by ID, including metadata and revocation status.

DELETE /api/v1/threats/{threat_id}

Revoke a threat. The record stays on chain for audit. Query param: reason.

Chain & Nodes

GET /api/v1/chain/status

Detailed chain info: peers, stream statistics, block count.

GET /api/v1/nodes

List nodes with latest heartbeats (chain height, threats enforced, uptime).

GET /api/v1/stats

Aggregate statistics: total/active threats, breakdowns by category, severity, source.

GET /api/v1/events

SSE stream. Events: threat_added, threat_revoked. Query param: token (API key).

Code Examples

# Add a threat
curl -X POST https://setecastronomyinc.com/api/v1/threats \
  -H "Authorization: Bearer tck_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "203.0.113.45",
    "source": "manual",
    "category": "ssh-brute-force",
    "severity": "high",
    "action": "block",
    "ttl_seconds": 86400
  }'

# List active threats
curl -s https://setecastronomyinc.com/api/v1/threats \
  -H "Authorization: Bearer tck_your_key" | jq .

# Revoke a threat
curl -X DELETE "https://setecastronomyinc.com/api/v1/threats/TC-ABC123?reason=false+positive" \
  -H "Authorization: Bearer tck_your_key"

# pip install httpx
import httpx

API = "https://setecastronomyinc.com"
KEY = "tck_your_key"
headers = {"Authorization": f"Bearer {KEY}"}

# Add a threat
resp = httpx.post(f"{API}/api/v1/threats", json={
    "target": "203.0.113.45",
    "source": "manual",
    "category": "ssh-brute-force",
    "severity": "high",
}, headers=headers)
print(resp.json())

# List threats
threats = httpx.get(f"{API}/api/v1/threats", headers=headers).json()
for t in threats:
    print(t["data"]["target"], t["data"]["severity"])

// Fetch + SSE example
const API = 'https://setecastronomyinc.com';
const KEY = 'tck_your_key';

// Add a threat
const resp = await fetch(`${API}/api/v1/threats`, {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${KEY}`,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        target: '203.0.113.45',
        source: 'manual',
        severity: 'high',
    }),
});
console.log(await resp.json());

// SSE streaming
const es = new EventSource(`${API}/api/v1/events?token=${KEY}`);
es.addEventListener('threat_added', (e) => {
    console.log('New threat:', JSON.parse(e.data));
});

SSE Streaming

The /api/v1/events endpoint provides real-time threat updates via Server-Sent Events. Connect with EventSource (browser) or any SSE client.

Event types:

threat_added — new threat published to the blockchain
threat_revoked — existing threat revoked

Pass your API key as a query parameter: ?token=tck_your_key

SSE access requires a Professional or Enterprise plan.

Rate Limits

Endpoint	Limit
`GET /health`	120/min
`POST /api/v1/threats`	60/min
`GET /api/v1/threats`	120/min
`DELETE /api/v1/threats/{id}`	30/min
`GET /api/v1/stats`	60/min
`GET /api/v1/events`	10/min

Rate limits are per IP address. Exceeding the limit returns 429 Too Many Requests.

Error Handling

The API returns standard HTTP status codes with JSON error bodies:

{
    "detail": "Invalid API key"
}

Code	Meaning
`200`	Success
`201`	Created (new threat published)
`401`	Missing or invalid API key
`403`	Insufficient privileges (admin required)
`404`	Threat not found
`422`	Invalid input (bad IP, whitelist rejection)
`429`	Rate limit exceeded
`503`	Blockchain unavailable