N.L.D.S. API Reference

Overview

The N.L.D.S. (Natural Language Detection System) API provides comprehensive natural language processing capabilities as the Tier 0 component of the JAEGIS Enhanced Agent System. This reference documentation covers all available endpoints, request/response formats, and integration patterns.

Base Information

Base URL: https://api.jaegis.ai/v2
Protocol: HTTPS only
Content-Type: application/json
API Version: 2.2.0
Rate Limiting: Tier-based (see Rate Limiting)

Authentication

JWT Token (Recommended)

Authorization: Bearer <jwt_token>

API Key

X-API-Key: <api_key>

Core Endpoints

POST /process

Process natural language input and generate JAEGIS commands.

Request

POST /process
Content-Type: application/json
Authorization: Bearer <jwt_token>

Request Body Schema:

{
  "input_text": "string (required)",
  "user_id": "string (optional)",
  "session_id": "string (optional)",
  "processing_dimensions": ["logical", "emotional", "creative"] (optional),
  "preferred_mode": 1-5 (optional),
  "preferred_squad": "string (optional)",
  "context": {} (optional),
  "require_high_confidence": true (optional),
  "timeout_ms": 5000 (optional)
}

Field Descriptions:

Field

Type

Required

Description

input_text

string

Yes

Natural language input to process (1-10000 chars)

user_id

string

User identifier for personalization

session_id

string

Session identifier for context continuity

processing_dimensions

array

Dimensions to analyze: logical, emotional, creative, all

preferred_mode

integer

JAEGIS operation mode (1-5)

preferred_squad

string

Preferred squad for execution

context

object

Additional context information

require_high_confidence

boolean

Require ≥85% confidence (default: true)

timeout_ms

integer

Processing timeout in milliseconds

Response

Success Response (200):

{
  "request_id": "req_abc123def456",
  "processing_timestamp": "2024-01-15T10:30:00.123Z",
  "total_processing_time_ms": 245.7,
  "dimensional_analysis": [
    {
      "dimension": "logical",
      "confidence": 0.92,
      "analysis_result": {
        "intent": "create_authentication_system",
        "complexity": "medium",
        "technical_requirements": ["jwt", "security", "authentication"],
        "estimated_effort": "4-6 hours",
        "risk_factors": ["security_implementation", "integration_complexity"]
      },
      "processing_time_ms": 89.3
    },
    {
      "dimension": "emotional",
      "confidence": 0.78,
      "analysis_result": {
        "user_sentiment": "determined",
        "urgency_level": "medium",
        "satisfaction_factors": ["security", "reliability", "ease_of_use"]
      },
      "processing_time_ms": 67.2
    },
    {
      "dimension": "creative",
      "confidence": 0.85,
      "analysis_result": {
        "alternative_approaches": ["oauth2", "saml", "biometric"],
        "innovation_opportunities": ["passwordless_auth", "ai_behavior_analysis"],
        "design_patterns": ["decorator", "strategy", "factory"]
      },
      "processing_time_ms": 89.2
    }
  ],
  "overall_confidence": 0.89,
  "confidence_level": "high",
  "primary_command": {
    "command": "FRED:IMPLEMENT --component=auth --security=jwt --mode=secure --priority=high",
    "mode": 3,
    "squad": "development",
    "parameters": {
      "component": "authentication_system",
      "security_level": "high",
      "token_type": "jwt",
      "implementation_pattern": "secure_by_default",
      "testing_required": true
    },
    "confidence": 0.89,
    "estimated_duration": "4-6 hours",
    "dependencies": ["security_framework", "database_schema"]
  },
  "alternative_interpretations": [
    {
      "command": "ARCHITECT:DESIGN --system=auth --pattern=jwt --security=high",
      "confidence": 0.76,
      "reasoning": "Design-first approach for complex authentication system",
      "mode": 4,
      "squad": "architecture"
    },
    {
      "command": "SECURITY:AUDIT --component=auth --framework=jwt",
      "confidence": 0.71,
      "reasoning": "Security-focused analysis of authentication requirements",
      "mode": 3,
      "squad": "security"
    }
  ],
  "context_updates": {
    "last_intent": "create_authentication_system",
    "session_complexity": "medium",
    "user_preferences": {
      "security_focus": true,
      "implementation_speed": "balanced"
    },
    "project_context": {
      "technology_stack": "inferred_python",
      "architecture_pattern": "microservices"
    }
  },
  "warnings": [],
  "metadata": {
    "model_versions": {
      "nlp_engine": "2.2.0",
      "intent_classifier": "1.5.2",
      "confidence_scorer": "1.3.1"
    },
    "processing_pipeline": ["tokenization", "semantic_analysis", "intent_recognition", "command_generation"],
    "quality_metrics": {
      "input_clarity": 0.91,
      "context_richness": 0.67,
      "output_specificity": 0.88
    }
  }
}

Error Responses:

// 400 Bad Request
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Input text is required and cannot be empty",
    "details": {
      "field": "input_text",
      "provided_value": "",
      "expected_format": "non-empty string (1-10000 characters)"
    },
    "request_id": "req_error123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

// 401 Unauthorized
{
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Valid authentication token required",
    "details": {
      "auth_methods": ["jwt_token", "api_key"],
      "token_format": "Bearer <token> or X-API-Key: <key>"
    },
    "request_id": "req_auth_error",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

// 429 Too Many Requests
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Request rate limit exceeded for your tier",
    "details": {
      "current_tier": "basic",
      "limit_per_minute": 100,
      "requests_made": 101,
      "reset_time": "2024-01-15T10:31:00Z"
    },
    "request_id": "req_rate_limit",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

POST /batch

Process multiple natural language inputs in a single request.

Request

{
  "inputs": [
    {
      "id": "input_1",
      "text": "Create a user authentication system with JWT tokens",
      "context": {
        "priority": "high",
        "project": "web_app"
      }
    },
    {
      "id": "input_2",
      "text": "Analyze system performance metrics and identify bottlenecks",
      "context": {
        "priority": "medium",
        "system": "production"
      }
    }
  ],
  "batch_options": {
    "parallel_processing": true,
    "return_partial_results": true,
    "max_processing_time_ms": 10000,
    "fail_fast": false
  },
  "default_options": {
    "processing_dimensions": ["logical", "creative"],
    "require_high_confidence": true
  }
}

Response

{
  "batch_id": "batch_xyz789abc123",
  "total_inputs": 2,
  "processed_inputs": 2,
  "failed_inputs": 0,
  "total_processing_time_ms": 456.2,
  "parallel_processing_used": true,
  "results": [
    {
      "input_id": "input_1",
      "status": "success",
      "processing_time_ms": 234.5,
      "result": {
        "primary_command": {
          "command": "FRED:IMPLEMENT --component=auth --security=jwt",
          "confidence": 0.91
        },
        "overall_confidence": 0.91
      }
    },
    {
      "input_id": "input_2",
      "status": "success",
      "processing_time_ms": 221.7,
      "result": {
        "primary_command": {
          "command": "TYLER:ANALYZE --metrics=performance --scope=bottlenecks",
          "confidence": 0.88
        },
        "overall_confidence": 0.88
      }
    }
  ],
  "batch_metadata": {
    "processing_efficiency": 0.94,
    "average_confidence": 0.895,
    "resource_utilization": {
      "cpu_usage": 0.67,
      "memory_usage": 0.45
    }
  }
}

GET /health

Check system health and operational status.

Response

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "2.2.0",
  "uptime_seconds": 86400,
  "components": {
    "nlp_engine": {
      "status": "operational",
      "response_time_ms": 12.3,
      "last_check": "2024-01-15T10:29:55Z"
    },
    "intent_recognition": {
      "status": "operational",
      "accuracy": 0.91,
      "last_check": "2024-01-15T10:29:55Z"
    },
    "translation_engine": {
      "status": "operational",
      "success_rate": 0.97,
      "last_check": "2024-01-15T10:29:55Z"
    },
    "jaegis_integration": {
      "status": "operational",
      "coordination_efficiency": 0.94,
      "last_check": "2024-01-15T10:29:55Z"
    },
    "database": {
      "status": "operational",
      "connection_pool": "85% utilized",
      "last_check": "2024-01-15T10:29:55Z"
    },
    "cache": {
      "status": "operational",
      "hit_ratio": 0.89,
      "last_check": "2024-01-15T10:29:55Z"
    }
  },
  "performance_metrics": {
    "avg_response_time_ms": 234.5,
    "requests_per_minute": 847,
    "confidence_accuracy": 0.91,
    "error_rate": 0.012,
    "uptime_percentage": 99.97
  },
  "resource_usage": {
    "cpu_usage": 0.45,
    "memory_usage": 0.62,
    "disk_usage": 0.23,
    "network_io": "moderate"
  }
}

GET /user/{user_id}/profile

Retrieve user profile and processing preferences.

Response

{
  "user_id": "user123",
  "profile": {
    "created_at": "2024-01-01T00:00:00Z",
    "last_active": "2024-01-15T10:25:00Z",
    "tier": "premium",
    "status": "active"
  },
  "preferences": {
    "default_processing_dimensions": ["logical", "creative"],
    "preferred_squad": "development",
    "confidence_threshold": 0.85,
    "timeout_preference": 5000,
    "language": "en",
    "notification_settings": {
      "low_confidence_alerts": true,
      "processing_complete": false
    }
  },
  "usage_statistics": {
    "total_requests": 1247,
    "requests_this_month": 89,
    "avg_confidence": 0.87,
    "most_common_intents": [
      {"intent": "create", "count": 234, "percentage": 18.8},
      {"intent": "implement", "count": 187, "percentage": 15.0},
      {"intent": "analyze", "count": 156, "percentage": 12.5}
    ],
    "preferred_squads": [
      {"squad": "development", "count": 567, "percentage": 45.5},
      {"squad": "analysis", "count": 234, "percentage": 18.8},
      {"squad": "security", "count": 123, "percentage": 9.9}
    ]
  },
  "session_context": {
    "active_sessions": 2,
    "current_session_id": "session456",
    "session_start": "2024-01-15T09:30:00Z",
    "context_data": {
      "recent_intents": ["create", "implement"],
      "project_context": "web_application",
      "complexity_trend": "increasing"
    }
  },
  "rate_limiting": {
    "current_tier": "premium",
    "requests_remaining_minute": 456,
    "requests_remaining_hour": 4567,
    "requests_remaining_day": 45678,
    "reset_times": {
      "minute": "2024-01-15T10:31:00Z",
      "hour": "2024-01-15T11:00:00Z",
      "day": "2024-01-16T00:00:00Z"
    }
  }
}

GET /metrics

Retrieve real-time system metrics and analytics.

Response

{
  "timestamp": "2024-01-15T10:30:00Z",
  "current_load": {
    "requests_per_second": 23.4,
    "avg_response_time_ms": 234.5,
    "active_sessions": 156,
    "queue_depth": 12
  },
  "confidence_metrics": {
    "avg_confidence": 0.87,
    "high_confidence_rate": 0.73,
    "medium_confidence_rate": 0.15,
    "low_confidence_rate": 0.12,
    "confidence_distribution": {
      "0.9-1.0": 0.45,
      "0.8-0.9": 0.28,
      "0.7-0.8": 0.15,
      "0.6-0.7": 0.08,
      "0.0-0.6": 0.04
    }
  },
  "processing_metrics": {
    "avg_processing_time_ms": 234.5,
    "p95_processing_time_ms": 456.7,
    "p99_processing_time_ms": 789.1,
    "timeout_rate": 0.002,
    "retry_rate": 0.015
  },
  "system_health": {
    "cpu_usage": 0.45,
    "memory_usage": 0.62,
    "disk_usage": 0.23,
    "network_latency_ms": 12.3,
    "database_connections": 85,
    "cache_hit_ratio": 0.89
  },
  "error_metrics": {
    "total_error_rate": 0.012,
    "4xx_error_rate": 0.008,
    "5xx_error_rate": 0.004,
    "timeout_error_rate": 0.002,
    "common_errors": [
      {"code": "INVALID_INPUT", "count": 23, "percentage": 45.1},
      {"code": "RATE_LIMIT_EXCEEDED", "count": 12, "percentage": 23.5},
      {"code": "TIMEOUT", "count": 8, "percentage": 15.7}
    ]
  }
}

Rate Limiting

N.L.D.S. implements intelligent rate limiting based on user tiers:

Tier

Requests/Minute

Requests/Hour

Requests/Day

Burst Capacity

Basic

100

1,000

10,000

Premium

500

5,000

50,000

100

Enterprise

1,000

10,000

100,000

200

Unlimited

∞

Rate Limit Headers

All responses include rate limiting information:

X-RateLimit-Limit-Minute: 100
X-RateLimit-Remaining-Minute: 87
X-RateLimit-Reset-Minute: 2024-01-15T10:31:00Z
X-RateLimit-Limit-Hour: 1000
X-RateLimit-Remaining-Hour: 923
X-RateLimit-Reset-Hour: 2024-01-15T11:00:00Z

Error Handling

Standard Error Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "problematic_field",
      "provided_value": "invalid_value",
      "expected_format": "expected_format_description"
    },
    "request_id": "req_error_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "documentation_url": "https://docs.jaegis.ai/errors/ERROR_CODE"
  }
}

Common Error Codes

Code

HTTP Status

Description

INVALID_INPUT

400

Request validation failed

AUTHENTICATION_REQUIRED

401

Authentication token missing or invalid

INSUFFICIENT_PERMISSIONS

403

User lacks required permissions

RESOURCE_NOT_FOUND

404

Requested resource does not exist

RATE_LIMIT_EXCEEDED

429

Request rate limit exceeded

PROCESSING_TIMEOUT

408

Request processing timed out

INTERNAL_ERROR

500

Internal server error

SERVICE_UNAVAILABLE

503

Service temporarily unavailable

Webhooks

Configure webhooks to receive real-time notifications:

Webhook Events

processing_complete: Processing finished successfully
high_confidence_result: Result with confidence ≥95%
low_confidence_result: Result with confidence <70%
processing_error: Processing failed
rate_limit_warning: Approaching rate limit

Webhook Payload

{
  "event": "processing_complete",
  "timestamp": "2024-01-15T10:30:00Z",
  "webhook_id": "webhook_abc123",
  "data": {
    "request_id": "req_abc123",
    "user_id": "user123",
    "confidence": 0.89,
    "primary_command": "FRED:IMPLEMENT --component=auth",
    "processing_time_ms": 234.5
  },
  "signature": "sha256=abc123def456..."
}

API Version: 2.2.0 Last Updated: January 15, 2024 Support: api-support@jaegis.ai

PreviousJAEGIS API Reference NextN.L.D.S. API Documentation

Last updated 4 months ago

Good evening

hashtagOverview

hashtagBase Information

hashtagAuthentication

hashtagJWT Token (Recommended)

hashtagAPI Key

hashtagCore Endpoints

hashtagPOST /process

hashtagRequest

hashtagResponse

hashtagPOST /batch

hashtagRequest

hashtagResponse

hashtagGET /health

hashtagResponse

hashtagGET /user/{user_id}/profile

hashtagResponse

hashtagGET /metrics

hashtagResponse

hashtagRate Limiting

hashtagRate Limit Headers

hashtagError Handling

hashtagStandard Error Format

hashtagCommon Error Codes

hashtagWebhooks

hashtagWebhook Events

hashtagWebhook Payload

Overview

Base Information

Authentication

JWT Token (Recommended)

API Key

Core Endpoints

POST /process

Request

Response

POST /batch

Request

Response

GET /health

Response

GET /user/{user_id}/profile

Response

GET /metrics

Response

Rate Limiting

Rate Limit Headers

Error Handling

Standard Error Format

Common Error Codes

Webhooks

Webhook Events

Webhook Payload