NEXUS-MM API Documentation

v8.1.1 · Universal Learning Engine

A world model that learns physics from scratch and tells robots when to stop, slow down, or go.

What is NEXUS-MM?

NEXUS-MM is a universal learning engine for robots. You send it a surface type and the robot's current speed. It returns a safe decision — go, slow_down, stop, or caution — along with a risk score.

What you get with every call

Decision — the action the robot should take
Risk score — 0.0 (safe) to 1.0 (critical)
Risk level — safe, moderate, high, or critical
Confidence — how sure NEXUS is about the decision

Designed for

Warehouse AGVs
Construction quadrupeds
Racing humanoids
Delivery robots
Any robot that moves on varying surfaces

Quick Start — Python SDK

The fastest way to get NEXUS-MM running in your robot.

Install

pip install nexus-mm-sdk

Set your API key

After subscribing, copy your API key from the dashboard and set it as an environment variable:

export NEXUS_API_KEY="nxk_your_key_here"

Ask NEXUS for a decision

from nexus_sdk import NexusRobot

robot = NexusRobot()  # reads NEXUS_API_KEY from environment

# What should the robot do on ice at 0.8 m/s?
d = robot.decide(action="move_forward", surface="ice", speed=0.8)
print(d.action)        # "stop"
print(d.risk)          # 0.75
print(d.risk_level)    # "critical"
print(d.confidence)    # 0.92

# Check backend health
print(robot.health())
# {'status': 'healthy', 'version': '8.1.1', ...}

With obstacle awareness

d = robot.decide(
    action="move_forward",
    surface="concrete",
    speed=0.5,
    distance_to_obstacle=1.2
)
# Backend applies hard safety override if the obstacle is too close
print(d.action)  # "stop"

💡 Tip: Call decide() at least 5–10 times per second for smooth control. NEXUS is fast (~80 ms per call).

Quick Start — REST API

If you're not using Python, call NEXUS directly over HTTP.

Endpoint

POST https://api.nexusmm.site/api/robot/decide

Example with curl

curl -X POST https://api.nexusmm.site/api/robot/decide \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxk_your_key_here" \
  -d '{
    "action": "move_forward",
    "surface": "ice",
    "speed": 0.8
  }'

Response

{
  "action": "stop",
  "risk": 0.75,
  "risk_level": "critical",
  "confidence": 0.92,
  "surface": "ice",
  "speed": 0.8
}

Example with JavaScript

const res = await fetch("https://api.nexusmm.site/api/robot/decide", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "nxk_your_key_here"
  },
  body: JSON.stringify({
    action: "move_forward",
    surface: "ice",
    speed: 0.8
  })
});
const decision = await res.json();
console.log(decision.action);  // "stop"
console.log(decision.risk);    // 0.75

Authentication

Every API request must include your API key in the X-API-Key header. Your key starts with nxk_.

Getting your API key

Log in to nexusmm.site/login
On the dashboard, find the API Key field at the top
Click Copy Key

⚠️ Security: Never share your API key. Never commit it to Git. Always call the API over HTTPS — your key travels in a header and must never be sent over plain HTTP.

Dashboard vs API access

Access type	Authentication	Free?
Dashboard	JWT (from login)	Yes — free forever
SDK / API	X-API-Key header	No — paid tier required

API Reference

POST /api/robot/decide

Main decision endpoint. Returns a safe action for the current robot state.

Request body

Field	Type	Required	Description
action	string	Yes	move_forward \| turn_left \| turn_right \| reverse \| stop
surface	string	Yes	Surface type (see Supported Surfaces)
speed	float	Yes	Speed in m/s (0.0–2.0 recommended)
distance_to_obstacle	float	No	Distance to obstacle in meters

Response fields

Field	Type	Description
action	string	go \| slow_down \| stop \| caution
risk	float	0.0 (safe) to 1.0 (critical)
risk_level	string	safe \| moderate \| high \| critical
confidence	float	0.0 to 1.0
surface	string	Surface type used for the decision
speed	float	Speed used for the decision

GET /api/usage/status

Check your current usage. Requires JWT.

curl https://api.nexusmm.site/api/usage/status \
  -H "Authorization: Bearer YOUR_JWT"

{
  "success": true,
  "tier": "Starter",
  "runs_used_this_month": 12,
  "runs_limit_monthly": 100000,
  "subscription_status": "active",
  "api_key": "nxk_..."
}

GET /api/subscription

Check subscription details. Requires JWT.

curl https://api.nexusmm.site/api/subscription \
  -H "Authorization: Bearer YOUR_JWT"

Supported Surfaces

NEXUS-MM categorizes surfaces into friction bands. Lower friction surfaces are riskier for robots. Each surface returns the appropriate risk level for the current speed.

Friction category	Example surfaces	Typical decision
High friction	concrete, tile, wood, carpet, grass, rocky	go
Moderate friction	gravel, sand, rubble, debris	slow_down
Low friction	wet_floor, mud, metal, ash, snow	stop
Critical (near-zero)	ice, slippery, oil, oil_spill, water	stop

You can pass any of the surface names above to the surface field.

Risk Levels

Every response includes a risk score between 0.0 and 1.0, and a risk level that maps to a decision.

Risk level	Meaning	Decision
safe	Proceed normally	go
moderate	Proceed with caution	slow_down
high	Reduce speed significantly	caution
critical	Stop immediately	stop

ℹ️ Hard safety overrides: Regardless of previous state, NEXUS forces stop when the computed risk crosses the critical threshold, and slow_down when it crosses the high threshold. Exact thresholds are proprietary and tuned per deployment.

Training Your Model

Training is available on Pro, Business, and Enterprise tiers only.

Training lets you feed real-world outcomes back into NEXUS so it learns. Send NEXUS what it predicted plus what actually happened. NEXUS records corrections and flags discoveries.

POST /api/robot/train

curl -X POST https://api.nexusmm.site/api/robot/train \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxk_your_key_here" \
  -d '{
    "predicted": {
      "surface": "concrete",
      "speed": 0.5,
      "action": "go"
    },
    "actual": {
      "surface": "concrete",
      "speed": 0.5,
      "action": "go",
      "outcome": "success",
      "notes": "robot crossed without slipping"
    }
  }'

Response

{
  "success": true,
  "learning_occurred": true,
  "corrections_count": 3,
  "discoveries_count": 1,
  "unknown_detected": false,
  "modules_affected": ["surfaces", "materials"],
  "message": "Learning complete: 3 corrections, 1 discoveries flagged"
}

GET /api/train/modules

See which modules have been trained and their accuracy.

curl https://api.nexusmm.site/api/train/modules \
  -H "X-API-Key: nxk_your_key_here"

GET /api/discoveries

See what NEXUS has discovered from training — new surfaces, new materials, unexpected behaviors.

curl https://api.nexusmm.site/api/discoveries \
  -H "X-API-Key: nxk_your_key_here"

Tiers & Limits

All prices are in Nigerian Naira (NGN). International cards are converted automatically by your bank at checkout.

Tier	Price (NGN/mo)	API calls / month	Training
Free	₦0	0 (dashboard only)	No
Starter	₦1,500	100,000	No

ℹ️ Counter reset: Usage counters reset on the 1st of every month at midnight UTC.

⚠️ Hitting the limit: Your next call returns HTTP 429. Your data and key are safe. Upgrade to continue.

Error Handling

HTTP	Meaning	Action
200	Success	Parse the response
400	Bad request	Check your JSON body
401	Invalid or missing API key	Check X-API-Key header
403	Free tier — no API access	Upgrade to Starter or higher
403	Training on lower tier	Upgrade to Pro+
429	Monthly limit reached	Upgrade or wait for reset
500	Server error	Retry after 30 seconds

Error response shape

{
  "success": false,
  "error": "Free tier has no SDK/API access. Please upgrade your plan.",
  "code": 403
}

Retry strategy

500: retry up to 3 times with a 5-second delay
429: do not retry — upgrade instead
401 / 403: do not retry — check credentials or upgrade

Billing

Processor: Paystack
Currency: Nigerian Naira (NGN)
Accepted: Visa, Mastercard, Verve, bank transfer, USSD, international cards (auto-converted)
Billing cycle: Monthly, on the same day each month
Cancel: From your dashboard → Cancel Subscription
Refunds: Contact support within 7 days
Receipts: Sent by Paystack to your email

Support

Email: support@nexusmm.site

Response time: Within 24 hours on business days.

Include in your message:

Your account email
The endpoint you called
The exact error message
The X-Request-ID header from the failed response

Quick Reference

API base URL https://api.nexusmm.site

Main endpoint POST /api/robot/decide

Auth header X-API-Key: nxk_...

Dashboard nexusmm.site

Signup nexusmm.site/signup

Subscribe nexusmm.site/subscribe

Support support@nexusmm.site

NEXUS-MM API Documentation

On This Page

What is NEXUS-MM?

What you get with every call

Designed for

Quick Start — Python SDK

Install

Set your API key

Ask NEXUS for a decision

With obstacle awareness

Quick Start — REST API

Endpoint

Example with curl

Response

Example with JavaScript

Authentication

Getting your API key

Dashboard vs API access

API Reference

POST /api/robot/decide

GET /api/usage/status

GET /api/subscription

Supported Surfaces

Risk Levels

Training Your Model

POST /api/robot/train

Response

GET /api/train/modules

GET /api/discoveries

Tiers & Limits

Error Handling

Error response shape

Retry strategy

Billing

Support

Quick Reference