API Endpoints

This document provides a comprehensive reference for all NopeSight API endpoints, including request/response formats, parameters, and examples.

Base URL

https://api.nopesight.com/v1

Common Headers

Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
X-Request-ID: <unique-request-id>

CMDB Endpoints

Configuration Items

List Configuration Items

GET /cmdb/ci

Query Parameters:

type (string): Filter by CI type (server, workstation, software, etc.)
status (string): Filter by status (active, inactive, maintenance)
page (integer): Page number (default: 1)
limit (integer): Items per page (default: 20, max: 100)
sort (string): Sort field (name, created_at, updated_at)
order (string): Sort order (asc, desc)
search (string): Search in name and description

Response:

{
  "data": [
    {
      "id": "ci_123456",
      "name": "PROD-WEB-01",
      "type": "server",
      "status": "active",
      "attributes": {
        "os": "Ubuntu 22.04",
        "ip_address": "10.0.1.10",
        "cpu_cores": 8,
        "memory_gb": 32
      },
      "relationships": {
        "count": 15,
        "href": "/cmdb/ci/ci_123456/relationships"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Get Configuration Item

GET /cmdb/ci/{id}

Response:

{
  "id": "ci_123456",
  "name": "PROD-WEB-01",
  "type": "server",
  "status": "active",
  "attributes": {
    "os": "Ubuntu 22.04",
    "ip_address": "10.0.1.10",
    "cpu_cores": 8,
    "memory_gb": 32,
    "disk_gb": 500,
    "location": "DC1-RACK-42",
    "serial_number": "SN123456789",
    "manufacturer": "Dell Inc.",
    "model": "PowerEdge R740"
  },
  "custom_fields": {
    "department": "IT",
    "cost_center": "CC-1001",
    "environment": "production"
  },
  "relationships": [
    {
      "id": "rel_789",
      "type": "runs_on",
      "target_ci": "ci_789",
      "target_name": "VMware Host 01"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z",
  "created_by": "admin@company.com",
  "updated_by": "admin@company.com"
}

Create Configuration Item

POST /cmdb/ci

Request Body:

{
  "name": "PROD-DB-01",
  "type": "server",
  "status": "active",
  "attributes": {
    "os": "RedHat 8.5",
    "ip_address": "10.0.2.20",
    "cpu_cores": 16,
    "memory_gb": 64
  },
  "custom_fields": {
    "department": "IT",
    "environment": "production"
  }
}

Response:

{
  "id": "ci_789012",
  "name": "PROD-DB-01",
  "message": "Configuration item created successfully"
}

Update Configuration Item

PUT /cmdb/ci/{id}

Request Body:

{
  "status": "maintenance",
  "attributes": {
    "memory_gb": 128
  },
  "custom_fields": {
    "maintenance_window": "2024-01-25T02:00:00Z"
  }
}

Delete Configuration Item

DELETE /cmdb/ci/{id}

Response:

{
  "message": "Configuration item deleted successfully"
}

Relationships

List Relationships

GET /cmdb/relationships

Query Parameters:

source_ci (string): Filter by source CI ID
target_ci (string): Filter by target CI ID
type (string): Filter by relationship type
include_ai (boolean): Include AI-discovered relationships

Response:

{
  "data": [
    {
      "id": "rel_123",
      "type": "depends_on",
      "source": {
        "id": "ci_123",
        "name": "Web Application",
        "type": "application"
      },
      "target": {
        "id": "ci_456",
        "name": "Database Server",
        "type": "server"
      },
      "attributes": {
        "port": 3306,
        "protocol": "mysql",
        "criticality": "high"
      },
      "discovered_by": "ai_agent",
      "confidence": 0.95,
      "created_at": "2024-01-20T10:00:00Z"
    }
  ]
}

Create Relationship

POST /cmdb/relationships

Request Body:

{
  "type": "depends_on",
  "source_ci": "ci_123",
  "target_ci": "ci_456",
  "attributes": {
    "port": 3306,
    "protocol": "mysql"
  }
}

Process Connections

Get Process Connections

GET /api/ci/{ciId}/process-connections

Description: Retrieves process-level network connections for a specific CI, grouped by process name and target IP.

Response:

{
  "groups": [
    {
      "processName": "Microsoft.Exchange.Imap4.exe",
      "targetIP": "10.161.161.10",
      "targetServer": "KSDC01",
      "targetCIId": "ci_789012",
      "connectionCount": 5,
      "ports": [3268],
      "firstSeen": "2024-01-20T10:00:00Z",
      "lastSeen": "2024-01-20T16:00:00Z"
    }
  ]
}

Discover Listening Process

GET /api/ci/{ciId}/listening-process/{port}

Description: Discovers which process is listening on a specific port on a target CI.

Path Parameters:

ciId (string): The CI ID to check
port (number): The port number to check

Response:

{
  "found": true,
  "process": {
    "name": "lsass.exe",
    "pid": 1024,
    "port": 3268,
    "protocol": "TCP",
    "description": "Local Security Authority Process"
  }
}

Find CI by IP Address

GET /api/ci/find-by-ip/{ip}

Description: Finds a CI by its IP address, searching across multiple IP fields including arrays and JSON structures.

Path Parameters:

ip (string): The IP address to search for

Response:

{
  "found": true,
  "ci": {
    "id": "ci_123456",
    "name": "KSDC01",
    "type": "server",
    "customFields": {
      "ip_address": "172.24.1.10",
      "all_ip_addresses": ["172.24.1.10", "10.161.161.10"]
    }
  }
}

Debug: Find CI by IP

GET /api/debug/find-ci-by-ip/{ip}

Description: Debug endpoint that shows all fields searched when looking up a CI by IP address.

Response:

{
  "searchedIp": "10.161.161.10",
  "query": {
    "$or": [
      {"customFields.ip_address": "10.161.161.10"},
      {"customFields.IP Address": "10.161.161.10"},
      {"customFields.all_ip_addresses": "10.161.161.10"}
    ]
  },
  "results": [...],
  "found": true
}

Discovery Endpoints

Discovery Scans

Submit Scan Data

POST /discovery/scan-data

Request Body:

{
  "scan_type": "network",
  "scanner_id": "agent_001",
  "timestamp": "2024-01-20T15:30:00Z",
  "data": {
    "discovered_hosts": [
      {
        "ip_address": "10.0.1.50",
        "hostname": "unknown-device",
        "mac_address": "00:1B:44:11:3A:B7",
        "open_ports": [22, 80, 443],
        "os_guess": "Linux"
      }
    ]
  }
}

Get Scan History

GET /discovery/scans

Query Parameters:

scanner_id (string): Filter by scanner
status (string): Filter by status (running, completed, failed)
from (datetime): Start date
to (datetime): End date

Discovery Tokens

Create Discovery Token

POST /discovery/tokens

Request Body:

{
  "name": "Production Scanner",
  "description": "Token for production network scanner",
  "expires_in": "365d",
  "scopes": ["discovery.submit", "discovery.read"]
}

Response:

{
  "id": "token_123",
  "token": "nsd_k_a1b2c3d4e5f6...",
  "name": "Production Scanner",
  "expires_at": "2025-01-20T00:00:00Z"
}

Event Management Endpoints

Events

List Events

GET /events

Query Parameters:

status (string): Filter by status (open, acknowledged, resolved)
severity (string): Filter by severity (critical, high, medium, low)
source (string): Filter by source system
ci_id (string): Filter by related CI
from (datetime): Start time
to (datetime): End time

Response:

{
  "data": [
    {
      "id": "evt_123456",
      "title": "High CPU Usage on PROD-WEB-01",
      "description": "CPU usage exceeded 90% threshold",
      "severity": "high",
      "status": "open",
      "source": "prometheus",
      "source_id": "alert_789",
      "affected_cis": ["ci_123456"],
      "metrics": {
        "cpu_usage": 92.5,
        "duration_minutes": 15
      },
      "created_at": "2024-01-20T16:00:00Z",
      "updated_at": "2024-01-20T16:15:00Z"
    }
  ]
}

Create Event

POST /events

Request Body:

{
  "title": "Database Connection Pool Exhausted",
  "description": "Connection pool limit reached on production database",
  "severity": "critical",
  "source": "application",
  "source_id": "app_alert_123",
  "affected_cis": ["ci_789012"],
  "metrics": {
    "active_connections": 100,
    "max_connections": 100
  }
}

Update Event Status

PATCH /events/{id}/status

Request Body:

{
  "status": "acknowledged",
  "comment": "Investigating the issue"
}

Event Correlation

Get Correlated Events

GET /events/{id}/correlations

Response:

{
  "primary_event": "evt_123456",
  "correlated_events": [
    {
      "id": "evt_123457",
      "correlation_score": 0.85,
      "correlation_type": "temporal",
      "reason": "Similar events occurred within 5 minutes"
    }
  ],
  "suggested_root_cause": {
    "ci_id": "ci_789012",
    "confidence": 0.78,
    "explanation": "Database server showing resource constraints"
  }
}

Reporting Endpoints

Reports

List Reports

GET /reports

Query Parameters:

category (string): Filter by category
created_by (string): Filter by creator
shared (boolean): Include shared reports

Generate Report

POST /reports/generate

Request Body:

{
  "template_id": "tpl_inventory",
  "parameters": {
    "ci_type": "server",
    "date_range": "last_30_days",
    "grouping": "location"
  },
  "format": "pdf",
  "delivery": {
    "method": "email",
    "recipients": ["admin@company.com"]
  }
}

Response:

{
  "report_id": "rpt_123456",
  "status": "generating",
  "estimated_completion": "2024-01-20T16:35:00Z",
  "status_url": "/reports/rpt_123456/status"
}

Get Report Status

GET /reports/{id}/status

Response:

{
  "report_id": "rpt_123456",
  "status": "completed",
  "completed_at": "2024-01-20T16:32:00Z",
  "download_url": "/reports/rpt_123456/download",
  "expires_at": "2024-01-27T16:32:00Z"
}

AI Analytics

Natural Language Query

POST /reports/ai/query

Request Body:

{
  "query": "Show me all servers with high CPU usage in the last week",
  "context": {
    "time_zone": "America/New_York",
    "include_predictions": true
  }
}

Response:

{
  "interpretation": {
    "entities": ["servers", "cpu_usage"],
    "time_range": "last_7_days",
    "filters": {
      "ci_type": "server",
      "metric": "cpu_usage",
      "threshold": ">80%"
    }
  },
  "results": [
    {
      "ci_id": "ci_123456",
      "name": "PROD-WEB-01",
      "avg_cpu": 85.2,
      "peak_cpu": 98.5,
      "duration_above_threshold": "4h 23m"
    }
  ],
  "insights": [
    "3 servers consistently exceed 80% CPU usage during business hours",
    "CPU spikes correlate with batch job execution at 2 AM"
  ],
  "recommendations": [
    {
      "action": "Scale up PROD-WEB-01",
      "impact": "Reduce CPU usage by ~30%",
      "confidence": 0.82
    }
  ]
}

AI Agents Endpoints

Agent Management

List Agents

GET /agents

Response:

{
  "data": [
    {
      "id": "agent_123",
      "name": "Infrastructure Optimizer",
      "type": "infrastructure",
      "status": "active",
      "capabilities": [
        "capacity_planning",
        "cost_optimization",
        "performance_tuning"
      ],
      "performance": {
        "decisions_made": 1523,
        "success_rate": 0.92,
        "avg_confidence": 0.85
      }
    }
  ]
}

Query Agent

POST /agents/{id}/query

Request Body:

{
  "query": "What servers need capacity upgrades?",
  "context": {
    "time_range": "next_quarter",
    "budget_limit": 50000
  }
}

Response:

{
  "agent_id": "agent_123",
  "response": {
    "summary": "5 servers require capacity upgrades based on growth projections",
    "details": [
      {
        "ci_id": "ci_123456",
        "name": "PROD-DB-01",
        "current_capacity": {
          "cpu": "80%",
          "memory": "75%",
          "storage": "92%"
        },
        "projected_exhaustion": "2024-03-15",
        "recommended_upgrade": {
          "memory": "+32GB",
          "storage": "+500GB"
        },
        "estimated_cost": 12500
      }
    ],
    "confidence": 0.87,
    "reasoning": "Based on 6-month growth trend and seasonal patterns"
  }
}

Service Mapping Endpoints

Business Services

List Business Services

GET /services

Response:

{
  "data": [
    {
      "id": "svc_123",
      "name": "Customer Portal",
      "description": "External customer-facing portal",
      "criticality": "high",
      "sla": {
        "availability": "99.9%",
        "response_time": "< 2s"
      },
      "components": [
        {
          "ci_id": "ci_123",
          "role": "web_server"
        },
        {
          "ci_id": "ci_456",
          "role": "database"
        }
      ],
      "health": {
        "status": "healthy",
        "score": 98.5
      }
    }
  ]
}

Get Service Dependencies

GET /services/{id}/dependencies

Response:

{
  "service_id": "svc_123",
  "dependencies": {
    "upstream": [
      {
        "service_id": "svc_456",
        "name": "Authentication Service",
        "type": "required",
        "impact": "full_outage"
      }
    ],
    "downstream": [
      {
        "service_id": "svc_789",
        "name": "Analytics Service",
        "type": "optional",
        "impact": "degraded_functionality"
      }
    ]
  },
  "dependency_map": {
    "visualization_url": "/services/svc_123/dependency-map.svg"
  }
}

Webhook Endpoints

Webhook Management

Register Webhook

POST /webhooks

Request Body:

{
  "name": "Incident Webhook",
  "url": "https://myapp.com/webhooks/nopesight",
  "events": [
    "ci.created",
    "ci.updated",
    "event.created",
    "event.status_changed"
  ],
  "headers": {
    "X-Custom-Auth": "secret-token"
  },
  "active": true
}

Response:

{
  "id": "webhook_123",
  "name": "Incident Webhook",
  "url": "https://myapp.com/webhooks/nopesight",
  "secret": "whsec_a1b2c3d4e5f6",
  "created_at": "2024-01-20T17:00:00Z"
}

Webhook Payload Examples

CI Created Event

{
  "event": "ci.created",
  "timestamp": "2024-01-20T17:05:00Z",
  "data": {
    "ci": {
      "id": "ci_987654",
      "name": "NEW-SERVER-01",
      "type": "server"
    }
  },
  "webhook_id": "webhook_123",
  "delivery_id": "delivery_456"
}

Error Responses

Standard Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "ci_type",
        "error": "Invalid CI type 'invalid_type'"
      }
    ],
    "request_id": "req_123456",
    "documentation_url": "https://docs.nopesight.com/api/errors#VALIDATION_ERROR"
  }
}

Common Error Codes

HTTP Status	Error Code	Description
400	VALIDATION_ERROR	Invalid request parameters
401	AUTHENTICATION_REQUIRED	Missing or invalid authentication
403	PERMISSION_DENIED	Insufficient permissions
404	RESOURCE_NOT_FOUND	Requested resource not found
409	CONFLICT	Resource conflict (e.g., duplicate)
429	RATE_LIMIT_EXCEEDED	Too many requests
500	INTERNAL_ERROR	Internal server error
503	SERVICE_UNAVAILABLE	Service temporarily unavailable

Pagination

All list endpoints support pagination:

GET /cmdb/ci?page=2&limit=50

Pagination Response Headers:

X-Total-Count: 500
X-Page: 2
X-Per-Page: 50
X-Total-Pages: 10
Link: <https://api.nopesight.com/v1/cmdb/ci?page=3&limit=50>; rel="next",
      <https://api.nopesight.com/v1/cmdb/ci?page=1&limit=50>; rel="first",
      <https://api.nopesight.com/v1/cmdb/ci?page=10&limit=50>; rel="last"

Rate Limiting

API rate limits per authentication method:

Method	Rate Limit	Burst
API Key	1000/hour	100/minute
JWT Token	5000/hour	500/minute
Service Account	10000/hour	1000/minute

Versioning

The API uses URL versioning. The current version is v1.

Deprecation Policy:

New versions announced 6 months before release
Previous versions supported for 12 months
Deprecation warnings in headers:

X-API-Deprecation-Date: 2025-01-01
X-API-Deprecation-Info: https://docs.nopesight.com/api/v2-migration

Base URL​

Common Headers​

CMDB Endpoints​

Configuration Items​

List Configuration Items​

Get Configuration Item​

Create Configuration Item​

Update Configuration Item​

Delete Configuration Item​

Relationships​

List Relationships​

Create Relationship​

Process Connections​

Get Process Connections​

Discover Listening Process​

Find CI by IP Address​

Debug: Find CI by IP​

Discovery Endpoints​

Discovery Scans​

Submit Scan Data​

Get Scan History​

Discovery Tokens​

Create Discovery Token​

Event Management Endpoints​

Events​

List Events​

Create Event​

Update Event Status​

Event Correlation​

Get Correlated Events​

Reporting Endpoints​

Reports​

List Reports​

Generate Report​

Get Report Status​

AI Analytics​

Natural Language Query​

AI Agents Endpoints​

Agent Management​

List Agents​

Query Agent​

Service Mapping Endpoints​

Business Services​

List Business Services​

Get Service Dependencies​

Webhook Endpoints​

Webhook Management​

Register Webhook​

Webhook Payload Examples​

CI Created Event​

Error Responses​

Standard Error Format​

Common Error Codes​

Pagination​

Rate Limiting​

Versioning​

Base URL

Common Headers

CMDB Endpoints

Configuration Items

List Configuration Items

Get Configuration Item

Create Configuration Item

Update Configuration Item

Delete Configuration Item

Relationships

List Relationships

Create Relationship

Process Connections

Get Process Connections

Discover Listening Process

Find CI by IP Address

Debug: Find CI by IP

Discovery Endpoints

Discovery Scans

Submit Scan Data

Get Scan History

Discovery Tokens

Create Discovery Token

Event Management Endpoints

Events

List Events

Create Event

Update Event Status

Event Correlation

Get Correlated Events

Reporting Endpoints

Reports

List Reports

Generate Report

Get Report Status

AI Analytics

Natural Language Query

AI Agents Endpoints

Agent Management

List Agents

Query Agent

Service Mapping Endpoints

Business Services

List Business Services

Get Service Dependencies

Webhook Endpoints

Webhook Management

Register Webhook

Webhook Payload Examples

CI Created Event

Error Responses

Standard Error Format

Common Error Codes

Pagination

Rate Limiting

Versioning