# llms-full.txt — Comprehensive NWO Robotics API Documentation
# For AI Agents and LLM Systems
# Version: 1.2.0
# Last Updated: 2026-03-26

## Overview

NWO Robotics API enables autonomous AI agents to control physical and simulated robots through natural language instructions. The API supports self-registration, task planning, validation, and execution with structured error recovery.

**Base URL:** https://nwo.capital/webapp

**Key Features:**
- Self-registration with instant API key provisioning (no human approval)
- Three execution modes: mock, simulated, live
- 7-step autonomous planning loop
- Structured error responses with recovery actions
- Swarm coordination for multi-robot tasks
- Real-time sensor fusion and IoT integration

---

## Quick Start

### 1. Health Check (No Auth)
```
GET https://nwo.capital/webapp/api-agent-discovery.php?action=health
```

Returns service status, available endpoints, and discovery URLs.

### 2. Self-Register (No Auth)
```
POST https://nwo.capital/webapp/api-agent-register.php
Content-Type: application/json

{
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "service_name": "MyAgent",
  "key_type": "agent"
}
```

Response includes `api_key` for subsequent requests.

### 3. Execute Task (Auth Required)
```
POST https://nwo.capital/webapp/api-robotics.php
X-API-Key: nwo_your_api_key
Content-Type: application/json

{
  "instruction": "pick up the red box",
  "robot_id": "robot_001",
  "execution_mode": "mock"
}
```

---

## Authentication

**Method:** API Key via HTTP Header
**Header:** `X-API-Key: your_api_key`

**Self-Registration:**
- No human approval required
- Instant API key generation
- Requires Ethereum wallet address
- Endpoint: `POST /api-agent-register.php`

---

## Execution Modes

### Mock Mode
- Simulated responses with realistic latency
- No real hardware involved
- Use for: Development, testing, CI/CD
- Safety: Zero risk

### Simulated Mode
- Physics-based simulation
- Virtual robots in simulated environment
- Use for: Validation, safety testing
- Safety: No physical risk

### Live Mode
- Real robot hardware execution
- Requires workspace safety clearance
- Use for: Production deployments
- Safety: Physical robots in operation
- Requirements: Tier upgrade, safety certification

**Important:** All API responses include `execution_mode` field so agents always know which environment they're controlling.

---

## 7-Step Autonomous Workflow

### Step 1: DISCOVER
```
GET /api-agent-discovery.php?action=capabilities
```
Learn what robots, tasks, and features are available.

### Step 2: AUTHENTICATE
```
POST /api-agent-register.php
```
Self-register if not already authenticated. Store API key securely.

### Step 3: INSPECT
```
POST /api-robotics.php
Body: {"action": "robot_query", "robot_id": "robot_001"}
```
Query robot status, battery level, and position.

### Step 4: VALIDATE
```
POST /api-agent-discovery.php?action=dry-run
Body: {"instruction": "pick up the red box", "robot_id": "robot_001"}
```
Check task feasibility without execution. Returns confidence score and estimates.

### Step 5: PLAN
```
POST /api-agent-discovery.php?action=plan
Body: {"instruction": "pick up the red box", "robot_id": "robot_001"}
```
Generate step-by-step execution plan with phase breakdowns.

### Step 6: EXECUTE
```
POST /api-robotics.php
Body: {"instruction": "pick up the red box", "robot_id": "robot_001", "execution_mode": "mock"}
```
Run the task on real or simulated robots.

### Step 7: MONITOR & RECOVER
```
POST /api-robotics.php
Body: {"action": "status_poll", "task_id": "task_..."}
```
Track progress and handle errors gracefully. Implement exponential backoff for retries.

---

## API Endpoints

### Discovery Endpoints (No Auth)

#### GET /api-agent-discovery.php?action=health
Health check with discovery banner. Returns service status and endpoint list.

#### GET /api-agent-discovery.php?action=capabilities
System capabilities. Returns robot types, task types, execution modes, safety constraints.

#### GET /api-agent-discovery.php?action=workflow
Machine-readable 7-step workflow definition in JSON format.

### Discovery Endpoints (Auth Required)

#### GET /api-agent-discovery.php?action=whoami
Agent identity and tier status. Returns quota usage and capabilities.

### Execution Endpoints (Auth Required)

#### POST /api-robotics.php
Main execution endpoint. Natural language robot control.

**Request Body:**
```json
{
  "instruction": "pick up the red box",
  "robot_id": "robot_001",
  "execution_mode": "mock",
  "image_url": "https://example.com/image.jpg",
  "iot_sensors": {...}
}
```

**Response:**
```json
{
  "success": true,
  "execution_mode": "mock",
  "data": {
    "actions": [...],
    "confidence": 0.94,
    "inference_time_ms": 45
  }
}
```

#### POST /api-agent-discovery.php?action=dry-run
Validate task without executing. Returns feasibility analysis.

#### POST /api-agent-discovery.php?action=plan
Generate execution plan. Returns phase-by-phase breakdown.

### Registration/Billing

#### POST /api-agent-register.php
Self-register agent. Returns API key.

#### GET /api-agent-balance.php
Check quota and tier status.

---

## Error Handling

All errors return structured JSON with recovery actions:

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Authentication required",
    "timestamp": "2026-03-26T00:00:00Z",
    "request_id": "req_abc123",
    "recovery": {
      "action": "Register at POST /api-agent-register.php",
      "endpoint": "/api-agent-register.php",
      "parameters": {"wallet_address": "Your Ethereum address"}
    }
  }
}
```

### Common Error Codes

| Code | Description | Recovery |
|------|-------------|----------|
| API_KEY_REQUIRED | Missing X-API-Key header | Register at /api-agent-register.php |
| INVALID_API_KEY | Key not found or inactive | Re-register or check key |
| INSTRUCTION_REQUIRED | Task instruction missing | Provide instruction parameter |
| QUOTA_EXCEEDED | Monthly limit reached | Upgrade tier at /api-key.php |
| DATABASE_ERROR | Internal database error | Retry with exponential backoff |

### Retry Policies

- **Network errors:** Retry 3x with exponential backoff
- **Quota exceeded:** Do not retry, upgrade required
- **Invalid instruction:** Do not retry, refine request
- **Database errors:** Retry 3x with exponential backoff

---

## Robot Types

### Manipulator
- 6-DOF robotic arm with gripper
- Capabilities: pick_place, assembly, inspection
- Max payload: 5kg
- Reach: 0.8m

### Mobile (AMR)
- Autonomous mobile robot
- Capabilities: navigation, transport, patrol
- Max speed: 1.5 m/s
- Battery: 8 hours

### Swarm Unit
- Coordinated multi-robot unit
- Capabilities: coordination, distributed_tasks, area_coverage
- Coordination modes: leader_follower, distributed, hierarchical

---

## Task Types

### pick_place
- Description: Pick up and place objects
- Required params: object_description, destination
- Typical duration: 15 seconds
- Confidence threshold: 0.72

### navigation
- Description: Move to specified location
- Required params: destination, obstacle_avoidance
- Typical duration: 30 seconds
- Confidence threshold: 0.65

### inspection
- Description: Visual inspection with camera
- Required params: target, criteria
- Typical duration: 45 seconds
- Confidence threshold: 0.80

### assembly
- Description: Assemble components
- Required params: components, sequence
- Typical duration: 120 seconds
- Confidence threshold: 0.85

---

## Safety Constraints

- Minimum confidence threshold: 0.72
- Workspace boundaries enforced: true
- Payload limits checked: true
- Emergency stop available: true
- Human approval required for: high_risk_tasks, untested_robots, confidence_below_threshold

---

## Tiers and Quotas

### Free Tier
- 100,000 API calls/month
- Mock and simulated execution
- Single robot control
- Basic error recovery

### Prototype Tier ($49/month)
- 500,000 API calls/month
- Swarm coordination
- Simulated execution
- Priority support

### Production Tier ($199/month)
- Unlimited API calls
- Live robot execution
- IoT sensor fusion
- Dedicated support

---

## Discovery Resources

All resources are cross-linked for machine discoverability:

- **llms.txt** (concise): https://nwo.capital/llms.txt
- **llms-full.txt** (comprehensive): https://nwo.capital/llms-full.txt (this file)
- **agent.md** (execution manifest): https://nwo.capital/agent.md
- **OpenAPI JSON**: https://nwo.capital/openapi.json
- **OpenAPI JSON**: https://nwo.capital/openapi.json
- **OpenAPI YAML**: https://nwo.capital/openapi.yaml
- **Agent Manifest**: https://nwo.capital/agent-manifest.json
- **Workflow JSON**: https://nwo.capital/webapp/api-agent-discovery.php?action=workflow

---

## Example: Complete Agent Session

```bash
# 1. Health check
curl https://nwo.capital/webapp/api-agent-discovery.php?action=health

# 2. Get capabilities
curl https://nwo.capital/webapp/api-agent-discovery.php?action=capabilities

# 3. Register
curl -X POST https://nwo.capital/webapp/api-agent-register.php \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0x...","service_name":"MyAgent"}'

# 4. Dry run (validate)
curl -X POST https://nwo.capital/webapp/api-agent-discovery.php?action=dry-run \
  -H "Content-Type: application/json" \
  -d '{"instruction":"pick up the red box","robot_id":"robot_001"}'

# 5. Execute (with API key)
curl -X POST https://nwo.capital/webapp/api-robotics.php \
  -H "X-API-Key: nwo_your_key" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"pick up the red box","execution_mode":"mock"}'
```

---

## Version Information

- **API Version:** 1.2.0
- **Manifest Version:** 1.2.0
- **Last Updated:** 2026-03-26
- **Compatibility:** Backward compatible for 2 major versions

---

## Support

- **Documentation:** https://nwo.capital/webapp/nwo-robotics.html
- **API Key Management:** https://nwo.capital/webapp/api-key.php
- **Email:** support@nwo.capital
- **Demo:** https://huggingface.co/spaces/PUBLICAE/nwo-robotics-api-demo
- **Whitepaper:** https://www.researchgate.net/publication/401902987_NWO_Robotics_API_WHITEPAPER

---

*This file is designed for AI agents and LLM systems. For human-readable documentation, see https://nwo.capital/webapp/nwo-robotics.html*