Network Analytics API

The Network Analytics API provides comprehensive access to network performance metrics, traffic analysis, and security insights through Cognix's network monitoring infrastructure.

---

Getting Started

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Please contact support at cognix.au/contact-us to obtain an API key.

---

API Reference

1. Network Performance API

Retrieve detailed network performance metrics including latency, throughput, and packet loss.

Endpoint: GET https://api.cognix.au/v1/network/performance

Query Parameters

Parameter	Type	Required	Description
network_id	string	Yes	Network identifier
date_range	string	Yes	Date range format: YYYY-MM-DDtoYYYY-MM-DD
metrics	string	No	Comma-separated list of specific metrics
granularity	string	No	Data granularity (1m, 5m, 1h, 1d)

Example Response

{
  "status": "success",
  "data": {
    "network_id": "net_123",
    "timeframe": {
      "start": "2024-01-01",
      "end": "2024-01-31"
    },
    "metrics": {
      "latency": {
        "average_ms": 25,
        "peak_ms": 150,
        "jitter_ms": 5
      },
      "throughput": {
        "average_mbps": 850,
        "peak_mbps": 1200,
        "utilization_percent": 75
      },
      "packet_loss": {
        "percentage": 0.02,
        "total_packets": 15000000
      }
    }
  }
}

---

2. Traffic Analysis API

Analyze network traffic patterns and bandwidth utilization.

Endpoint: GET https://api.cognix.au/v1/network/traffic

Query Parameters

Parameter	Type	Required	Description
network_id	string	Yes	Network identifier
date_range	string	Yes	Date range format: YYYY-MM-DDtoYYYY-MM-DD
protocol	string	No	Filter by protocol (TCP, UDP, ICMP)
application	string	No	Filter by application type

Example Response

{
  "status": "success",
  "data": {
    "total_traffic_gb": 15000,
    "protocol_breakdown": {
      "tcp": 75,
      "udp": 20,
      "icmp": 5
    },
    "top_applications": [
      {
        "name": "Web",
        "bandwidth_usage_gb": 5000,
        "percentage": 33.3
      }
    ],
    "peak_times": {
      "daily": "14:00-16:00 UTC",
      "weekly": "Wednesday"
    }
  }
}

---

3. Device Inventory API

Monitor and analyze connected devices and their status.

Endpoint: GET https://api.cognix.au/v1/network/devices

Query Parameters

Parameter	Type	Required	Description
network_id	string	Yes	Network identifier
device_type	string	No	Filter by device type
status	string	No	Filter by device status

Example Response

{
  "status": "success",
  "data": {
    "total_devices": 250,
    "device_types": {
      "routers": 10,
      "switches": 25,
      "endpoints": 215
    },
    "status_summary": {
      "active": 240,
      "inactive": 8,
      "maintenance": 2
    },
    "recent_changes": [
      {
        "device_id": "dev_123",
        "type": "status_change",
        "timestamp": "2024-01-31T15:00:00Z"
      }
    ]
  }
}

---

4. Network Topology API

Retrieve network topology and infrastructure relationships.

Endpoint: GET https://api.cognix.au/v1/network/topology

Query Parameters

Parameter	Type	Required	Description
network_id	string	Yes	Network identifier
depth	integer	No	Topology mapping depth (default: 3)
include_meta	boolean	No	Include metadata for each node

Example Response

{
  "status": "success",
  "data": {
    "nodes": [
      {
        "id": "node_123",
        "type": "router",
        "connections": ["node_124", "node_125"],
        "metadata": {
          "location": "Sydney-DC1",
          "model": "Cisco-9300"
        }
      }
    ],
    "links": [
      {
        "source": "node_123",
        "target": "node_124",
        "bandwidth": "10Gbps",
        "utilization": 65
      }
    ]
  }
}

---

5. QoS Monitoring API

Track and analyze Quality of Service metrics and policies.

Endpoint: GET https://api.cognix.au/v1/network/qos

Query Parameters

Parameter	Type	Required	Description
network_id	string	Yes	Network identifier
policy_id	string	No	Specific QoS policy identifier
date_range	string	Yes	Date range format: YYYY-MM-DDtoYYYY-MM-DD

Example Response

{
  "status": "success",
  "data": {
    "policies": [
      {
        "id": "qos_123",
        "name": "Voice Traffic",
        "metrics": {
          "packet_loss": 0.01,
          "latency_ms": 15,
          "jitter_ms": 2
        },
        "compliance": {
          "sla_met": true,
          "violations_24h": 0
        }
      }
    ]
  }
}

Error Handling

The Network Analytics API uses conventional HTTP response codes and provides detailed error messages to indicate the success or failure of requests.

Response Codes

Code	Description
200	Success - Request completed successfully
400	Bad Request - Invalid parameters or malformed request
401	Unauthorized - Invalid or missing API key
403	Forbidden - Valid API key but insufficient permissions
404	Not Found - Requested resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side error occurred
503	Service Unavailable - Temporary server maintenance

Error Response Format

All error responses follow this consistent format:

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context about the error",
      "suggestion": "Recommended action to resolve the error"
    }
  },
  "request_id": "unique-request-identifier"
}

Common Error Codes

Authentication Errors

Error Code	Description	Resolution
INVALID_API_KEY	The provided API key is not valid	Please contact support at https://cognix.au/contact-us to verify your API key
EXPIRED_API_KEY	The API key has expired	Generate a new API key
MISSING_API_KEY	No API key provided in the request	Include API key in Authorization header

Request Errors

Error Code	Description	Resolution
INVALID_NETWORK_ID	The specified network_id doesn't exist	Check network identifier
INVALID_DATE_RANGE	Date range format is incorrect or invalid	Use format: YYYY-MM-DDtoYYYY-MM-DD
MISSING_PARAMS	Required parameters are missing	Review required parameters in docs
INVALID_METRICS	Requested metrics are not valid	Check available metrics list

Rate Limiting

Error Code	Description	Resolution
RATE_LIMIT	Too many requests in specified time period	Implement exponential backoff
QUOTA_EXCEEDED	Monthly API quota has been exceeded	Upgrade your plan or wait for reset

Error Examples

Invalid API Key

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "details": {
      "suggestion": "Please contact support at https://cognix.au/contact-us to verify your API key"
    }
  },
  "request_id": "req_7a8b9c0d"
}

Invalid Parameters

{
  "status": "error",
  "error": {
    "code": "INVALID_DATE_RANGE",
    "message": "The provided date range is invalid",
    "details": {
      "field": "date_range",
      "provided": "2024-01-32to2024-02-01",
      "suggestion": "Please use format YYYY-MM-DDtoYYYY-MM-DD with valid dates"
    }
  },
  "request_id": "req_1d2e3f4g"
}

Rate Limit Exceeded

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT",
    "message": "Rate limit exceeded. Please retry after 60 seconds",
    "details": {
      "rate_limit": "100 requests per minute",
      "retry_after": 60,
      "suggestion": "Implement exponential backoff or reduce request frequency"
    }
  },
  "request_id": "req_4h5i6j7k"
}

Best Practices for Error Handling

1. Always check the status field in the response to determine success/failure
2. Implement retry logic with exponential backoff for rate limits (429) and server errors (5xx)
3. Log the request_id for all errors to facilitate support requests
4. Monitor error rates to detect potential issues with your implementation
5. Handle errors gracefully in your application to provide a good user experience

---