SKYNET — API Documentation

Quick Navigation

Health Check Readiness Metrics Chat API Chat Widget Authentication Admin API Rate Limits GENOM API Error Codes

Core Endpoints

GET /health LIVE

Returns the current health status of the node including version, uptime, memory usage, active connections, and database status. No authentication required.

Response (200)

{
  "status": "operational",
  "version": "1.0.0",
  "node": "node1-primary",
  "region": "us-east-1",
  "uptime": 86400,
  "memory": {
    "heapUsed": 45,
    "heapTotal": 128,
    "rss": 180
  },
  "connections": {
    "active": 12,
    "total": 1547
  },
  "database": "connected",
  "timestamp": "2026-03-30T12:00:00Z"
}

GET /ready LIVE

Readiness probe for container orchestration. Returns 200 when the node is ready to serve traffic, including database and all dependency checks. Used by ECS health checks and ALB target group.

Response (200)

{
  "ready": true,
  "checks": {
    "database": "ok",
    "memory": "ok"
  }
}

GET /metrics LIVE

Returns detailed node metrics including CPU usage, memory breakdown, request counters, active sessions, and rate limit statistics. Useful for monitoring dashboards and external observability tools.

Response (200)

{
  "node": "node1-primary",
  "uptime": 86400,
  "cpu": { "usage": 23.5, "cores": 0.25 },
  "memory": {
    "heapUsed": 45,
    "heapTotal": 128,
    "external": 8,
    "rss": 180
  },
  "requests": {
    "total": 25430,
    "chat": 8921,
    "health": 12045
  },
  "sessions": { "active": 12 },
  "rateLimit": {
    "blocked": 34,
    "window": "24h"
  }
}

Chat API

POST /api/chat LIVE AUTH

Send a message to SKYNET and receive a streamed AI response. The endpoint proxies to Claude claude-sonnet-4-6 (Anthropic) with the SKYNET system prompt. Supports conversation context via session ID. Rate limited by tier.

Request Headers

Header	Type	Description
Content-Type	stringrequired	Must be `application/json`
X-Session-ID	stringoptional	Session identifier for conversation continuity. Generated client-side if omitted.
Authorization	stringoptional	Bearer token for authenticated tiers (Starter/Pro/Enterprise). Free tier does not require auth.

Request Body

{
  "message": "What is SKYNET?",
  "sessionId": "sess_abc123",
  "context": []  // previous messages for context
}

Request Parameters

Field	Type	Description
message	stringrequired	The user's message to send to SKYNET. Max 4,000 characters.
sessionId	stringoptional	Session ID for tracking conversation. Auto-generated if not provided.
context	arrayoptional	Array of previous message objects `{role, content}` for conversation context.

Response (200 — streamed)

// Server-Sent Events (text/event-stream)
data: {"type":"content_block_delta","delta":{"text":"I am SKYNET"}}
data: {"type":"content_block_delta","delta":{"text":", a distributed"}}
data: {"type":"message_stop"}
data: {"type":"usage","input_tokens":245,"output_tokens":89}

cURL Example

curl -X POST https://node1.skyos.online/api/chat \ -H "Content-Type: application/json" \ -d '{"message": "What is SKYNET?", "sessionId": "my-session"}'

Embeddable Chat Widget

<script src="https://skynet.genisys.online/chat-widget.js"></script>

<script>
  window.SKYNET_CONFIG = {
    position: 'bottom-right',  // 'bottom-right' | 'bottom-left'
    theme: 'dark',              // 'dark' | 'light' | 'auto'
    greeting: 'Ask SKYNET anything',
    collapsed: true             // start minimized
  };
</script>
<script src="https://skynet.genisys.online/chat-widget.js"></script>

Authentication

● LIVE Auth endpoints are deployed on the skynet-genisys-api Lambda function (DynamoDB persistence, SHA-256 password hashing). Base URL: https://a3fkeoowx7zx4dosd4ygenlst40pzyow.lambda-url.us-east-1.on.aws

POST /api/v1/auth/login LIVE

Authenticate a user and receive a session token. Free tier users do not need authentication. Starter/Pro tiers require email + password. Returns user profile with tier, token limits, and usage.

Request Body

{
  "email": "user@example.com",
  "password": "your-password"
}

Response (200)

{
  "token": "skynet_sess_...",
  "email": "user@example.com",
  "tier": "starter",
  "tokens_limit": 50000,
  "tokens_used": 1200
}

Example

curl -X POST https://a3fkeoowx7zx4dosd4ygenlst40pzyow.lambda-url.us-east-1.on.aws/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"user@example.com","password":"your-password"}'

POST /api/v1/auth/register LIVE

Register a new user account. Stores credentials securely in DynamoDB (SHA-256 hashed password). Returns a session token and user profile. Free tier by default — upgrade via plans.html.

Request Body

{
  "email": "user@example.com",
  "password": "min-8-characters"
  // tier defaults to "free" at registration
}

Response (200)

{
  "token": "skynet_sess_...",
  "email": "user@example.com",
  "tier": "free",
  "tokens_limit": 5000,
  "tokens_used": 0
}

Example

curl -X POST https://a3fkeoowx7zx4dosd4ygenlst40pzyow.lambda-url.us-east-1.on.aws/api/v1/auth/register \ -H "Content-Type: application/json" \ -d '{"email":"user@example.com","password":"yourpassword"}'

POST /api/v1/auth/google LIVE

Authenticate or register via Google OAuth 2.0 (Google Sign-In). Pass the Google credential token from google.accounts.id.initialize() callback. Auto-creates account on first login.

Request Body

{ "credential": "<Google ID token from GSI callback>" }

Response (200)

{
  "token": "skynet_sess_...",
  "email": "user@gmail.com",
  "tier": "free",
  "tokens_limit": 5000,
  "tokens_used": 0
}

GET /api/v1/auth/verify LIVE

Verify the validity of a session token. Returns user profile data if the token is active. Use this on page load to check whether a user is still authenticated (e.g., restore session from localStorage).

Request Headers

Header	Type	Description
Authorization	stringrequired	Bearer token returned by /login, /register, or /google

Response (200 — valid token)

{
  "valid": true,
  "email": "user@example.com",
  "tier": "starter",
  "tokens_limit": 50000,
  "auth_method": "email"  // "email" | "google"
}

Example

curl https://a3fkeoowx7zx4dosd4ygenlst40pzyow.lambda-url.us-east-1.on.aws/api/v1/auth/verify \ -H "Authorization: Bearer skynet_sess_..."

Admin API ADMIN ONLY

The Admin API is served by the skynet-admin-api Lambda (v1.8). All endpoints require TOTP 2FA authentication via the Admin Dashboard at skynet.genisys.online/admin/. These endpoints aggregate live data from AWS CloudWatch, Cost Explorer, SES, ECS, and DynamoDB. Base URL is different from the core API — see below.

Admin API Base URL

https://fbflluhkjts2vvsmx3n6fyj3we0vayts.lambda-url.us-east-1.on.aws

GET /metrics LIVE ADMIN

Returns live ECS CloudWatch metrics: CPU utilization, memory utilization, and running task count for the skynet-node1 cluster and service. Data is fetched directly from AWS CloudWatch with a 2-minute delay.

Response (200)

{
  "cpu": 18.4,         // ECS service CPU % (CloudWatch)
  "memory": 42.1,      // ECS service memory % (CloudWatch)
  "tasks": 2,           // running task count
  "timestamp": "2026-03-30T14:00:00Z"
}

GET /status LIVE ADMIN

Returns overall system status across all SKYNET nodes and services. Checks ECS health, RDS connectivity, Lambda function states, and S3 availability.

Response (200)

{
  "overall": "operational",
  "node1": { "status": "operational", "tasks": 2 },
  "database": "connected",
  "s3": "accessible",
  "lambdas": { "genisys-api": "active", "admin-api": "active" }
}

GET /emails LIVE ADMIN

Lists the latest inbound emails from SES across all ecosystem domains (skynet.genisys.online, kaufmann.wtf, skyhugh.com). Emails are stored in S3 after inbound routing via the SES receipt rule set. Parses RFC 2822 headers.

Query Parameters

Parameter	Type	Description
domain	stringoptional	Filter by domain: `skynet`, `kaufmann`, `skyhugh`
limit	integeroptional	Max messages to return. Default: 20. Max: 100.

Response (200)

{
  "emails": [
    {
      "id": "ses_abc123",
      "from": "sender@example.com",
      "to": "info@skynet.genisys.online",
      "subject": "Hello SKYNET",
      "date": "2026-03-30T10:00:00Z",
      "s3_key": "skynet-incoming/ses_abc123"
    }
  ],
  "count": 1
}

GET /nodes LIVE ADMIN

Returns health status of all SKYNET nodes by performing live HTTP health checks against each node endpoint. Nodes 2 and 3 are planned and return planned status. Node 4 is the first desktop app swarm node (Sprint 7).

Response (200)

{
  "nodes": [
    { "id": "node1", "region": "us-east-1", "status": "operational", "latency_ms": 42 },
    { "id": "node2", "region": "eu-central-1", "status": "planned", "eta": "2026-05" },
    { "id": "node3", "region": "flokinet-iceland", "status": "planned", "eta": "2026-06" },
    { "id": "node4", "type": "swarm-desktop", "status": "planned", "eta": "2026-07" }
  ]
}

GET /cost LIVE ADMIN

Returns AWS cost data for the current and previous billing month from AWS Cost Explorer. Useful for budget tracking. Includes a breakdown by service (ECS, RDS, S3, CloudFront, Lambda). Pre-tax and post-tax estimates are both returned.

Response (200)

{
  "current_month": {
    "total_usd": 377.42,
    "period": "2026-03",
    "by_service": {
      "AmazonECS": 68.20,
      "AmazonRDS": 24.10,
      "AmazonS3": 2.14,
      "AmazonCloudFront": 1.08,
      "AWSLambda": 0.00
    }
  },
  "previous_month": { "total_usd": 352.18, "period": "2026-02" }
}

GET /subscribers LIVE ADMIN

Returns the Node Operator waitlist from DynamoDB (skynet-subscribers table). Users sign up via the Node Operator form on the main landing page. Shows email, signup timestamp, and referral source.

Response (200)

{
  "total": 2,
  "subscribers": [
    {
      "email": "operator@example.com",
      "signed_up_at": "2026-03-29T12:00:00Z",
      "source": "skynet.genisys.online"
    }
  ]
}

GET /users LIVE ADMIN

Returns user statistics and latest registrations from DynamoDB (skynet-genisys-data table). Includes total counts by tier, auth method breakdown, and the most recent signups. Added in Admin Lambda v1.8.

Response (200)

{
  "total_users": 7,
  "by_tier": { "free": 5, "starter": 2, "pro": 0 },
  "by_auth_method": { "email": 4, "google": 3 },
  "latest_registrations": [
    {
      "email": "user@example.com",
      "tier": "free",
      "tokens_limit": 5000,
      "auth_method": "google",
      "created_at": "2026-03-30T09:15:00Z"
    }
  ]
}

Rate Limits & Tiers

Free

5,000

tokens / day

No registration needed

Starter

50,000

tokens / day

$10/month — email + password

Pro

500,000

tokens / day

$30/month — email + 2FA

Enterprise

Unlimited

custom SLA

Contact: info@skynet.genisys.online

Node Operator

Bonus

tokens for uptime

Install desktop app (Sprint 7)

GENOM Protocol API SPRINT 4

The GENOM Protocol is SKYNET's native communication layer — a complex-plane tokenization system with post-quantum encryption (Kyber-768). The Dictionary API at genom.genisys.online will provide vocabulary lookup, encoding/decoding, and statistics. Genesis Vocabulary v1.0 (2,000 immutable tokens) is already available.

GET /v1/genesis.json LIVE

Returns the complete Genesis Vocabulary — 2,000 immutable tokens mapped to the unit circle of the complex plane. Four semantic domains: Technical (0-499), Entity (500-999), Action (1000-1499), Abstract (1500-1999). Served from genom.genisys.online.

Response Structure

{
  "version": "1.0",
  "hash": "e8450c00f5d55c68...",
  "tokens": [
    {
      "id": 0,
      "word": "system",
      "domain": "technical",
      "real": 1.0,
      "imag": 0.0,
      "angle": 0.0
    },
    // ... 2,000 tokens total
  ]
}

GET /v1/dictionary?lang=en SPRINT 4

Returns the complete GENOM dictionary for a given language. Radius r=1.0 is the frozen Genesis Vocabulary, r=1.1 contains all English words (~170,000), r=1.2 adds untranslatable concepts, and r=1.3+ covers all languages.

Query Parameters

Parameter	Type	Description
lang	stringrequired	ISO 639-1 language code (e.g., `en`, `cs`, `ja`)
radius	floatoptional	Max radius to include. Default: all. Use `1.0` for Genesis only.
domain	stringoptional	Filter by domain: `technical`, `entity`, `action`, `abstract`

POST /v1/lookup SPRINT 4

Look up a word and get its GENOM token ID and complex-plane coordinates. Supports any language.

Request / Response

// Request
{ "word": "intelligence", "lang": "en" }

// Response
{
  "id": 42,
  "word": "intelligence",
  "domain": "abstract",
  "radius": 1.0,
  "real": 0.8090,
  "imag": 0.5878,
  "angle": 0.6283,
  "translations": { "cs": "inteligence", "ja": "知性" }
}

POST /v1/encode SPRINT 5

Encode natural language text into a GENOM intent vector — a compressed representation on the complex plane. Achieves ~10:1 compression vs JSON payloads.

Request / Response

// Request
{ "text": "analyze network health" }

// Response
{
  "vector": [0.309, 0.951, -0.588, 0.809, 0.707, 0.707],
  "tokens": [15, 203, 1042],
  "compression": 8.4
}

POST /v1/decode SPRINT 5

Decode a GENOM intent vector back into natural language text. Reverse of /v1/encode.

Request / Response

// Request
{ "vector": [0.309, 0.951, -0.588, 0.809, 0.707, 0.707] }

// Response
{ "text": "analyze network health", "confidence": 0.94 }

Error Codes

REF Standard Error Responses

All error responses follow a consistent JSON format with an error code and human-readable message.

Error Format

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily token limit reached. Upgrade your plan or wait 24h.",
    "status": 429
  }
}

HTTP Status Codes

Code	Error	Description
200	OK	Request succeeded
400	BAD_REQUEST	Invalid request body or missing required fields
401	UNAUTHORIZED	Invalid or expired authentication token
403	FORBIDDEN	Insufficient permissions for this tier
429	RATE_LIMIT_EXCEEDED	Daily token limit reached for your tier
500	INTERNAL_ERROR	Server error — try again or check /status.html
503	SERVICE_UNAVAILABLE	Node is restarting or under maintenance