NOC L1 Agent API — api.d2c.in

Authentication

All API endpoints require a signed JWT passed as a Bearer token. Tokens are issued by the NOC Identity Service and expire after 8 hours.

STEP 01

Obtain Token

POST your agent credentials to https://auth.d2c.in/token to receive a signed JWT.

STEP 02

Attach to Requests

Include Authorization: Bearer <token> in every request header.

Example Request Header

    
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type:   application/json
X-Agent-ID:      agent-l1-prod-01
  

System Health

GET

https://api.d2c.in/v1/health

Returns operational status of all agent subsystems

▶

Response 200 OK

        
{
  "status": "healthy",
  "timestamp": 1709284800,
  "subsystems": {
    "freshservice": "connected",
    "nms": "connected",
    "ssh_pool": "ready",
    "alarm_correlator": "running",
    "llm_rca": "ready"
  },
  "agent": {
    "model": "mirav-l1-v3",
    "mode": "autonomous",
    "active_tasks": 4,
    "queue_depth": 11
  }
}
      

Tickets

Create and manage NOC tickets. Tickets are automatically synced with Freshservice. Support filtering by status, priority, device, and customer.

GET

/v1/tickets

List all tickets with optional filters

▶

Parameter	Type	Required	Description
status	string	optional	Filter by status: `open \| in_progress \| pending \| resolved \| closed`
priority	string	optional	Filter by priority: `P1 \| P2 \| P3 \| P4`
device_id	string	optional	Filter by device, e.g. `DEV-MUM-PE01`
customer_id	string	optional	Filter by customer, e.g. `CUST-1092`
page	integer	optional	Page number (default: 1)
page_size	integer	optional	Results per page (default: 20, max: 100)

200Paginated ticket list

POST

/v1/tickets

Create a new NOC ticket (optionally trigger auto-remediation)

▶

Field	Type	Required	Description
subject	string	required	Short ticket title
description	string	required	Full incident description
priority	enum	required	`P1 \| P2 \| P3 \| P4`
device_id	string	optional	Related device ID
alarm_ids	string[]	optional	Correlated alarm IDs
auto_remediate	boolean	optional	Trigger L1 auto-remediation (default: false)

Request Body

        
{
  "subject": "CRITICAL: Interface down — MUM-PE01 Gi0/0/1",
  "description": "Gi0/0/1 on MUM-PE01 down at 14:32 IST. CUST-1092 impacted.",
  "priority": "P1",
  "device_id": "DEV-MUM-PE01",
  "alarm_ids": ["ALM-20240301-0042"],
  "customer_id": "CUST-1092",
  "auto_remediate": true
}
      

201Ticket created 422Validation error

GET

/v1/tickets/{ticket_id}

Get a single ticket by ID

▶

Example Response 200 OK

        
{
  "ticket_id": "TKT-20240301-0088",
  "freshservice_id": "FS-98821",
  "subject": "CRITICAL: Interface down — MUM-PE01 Gi0/0/1 — CUST-1092 impacted",
  "status": "in_progress",
  "priority": "P1",
  "device_id": "DEV-MUM-PE01",
  "alarm_ids": ["ALM-20240301-0042", "ALM-20240301-0043"],
  "customer_id": "CUST-1092",
  "assigned_to": "agent-l1",
  "sla_breach_at": 1709286300,
  "auto_remediation_attempted": true,
  "escalated_to": null
}
      

Diagnostics

Run network diagnostics from the perspective of a specific device. Results include raw CLI output and an AI-generated analysis.

POST

/v1/diagnostics/run

Execute a diagnostic — ping, traceroute, BGP check, optical, interface, ARP, route lookup, port check

▶

Diagnostics run asynchronously on the device via SSH. Response is returned once the diagnostic completes (typically < 5s for ping/interface checks).

Field	Type	Required	Description
device_id	string	required	Device to run the diagnostic from, e.g. `DEV-MUM-PE01`
diagnostic_type	enum	required	`ping \| traceroute \| bgp_check \| interface_status \| optical_power \| arp_table \| route_lookup \| port_check`
target	string	optional	Target IP or prefix for ping/traceroute/BGP/route
interface	string	optional	Interface name for interface_status/optical, e.g. `Gi0/0/1`
parameters	object	optional	Additional parameters (port for port_check, count for ping, etc.)

Request — Ping CPE

        
{
  "device_id": "DEV-MUM-PE01",
  "diagnostic_type": "ping",
  "target": "192.168.100.2"
}
      

Response 202 Accepted

        
{
  "diagnostic_id": "DIAG-A1B2C3D4",
  "device_id": "DEV-MUM-PE01",
  "diagnostic_type": "ping",
  "status": "COMPLETED",
  "result": {
    "packets_sent": 10,
    "packets_received": 0,
    "packet_loss_pct": 100.0,
    "reachable": false
  },
  "analysis": "CPE unreachable — 100% packet loss. Physical link or CPE power failure."
}
      

Actions

Execute L1 remediation actions on devices. Always provide a ticket_id and reason for full audit trail. Use dry_run=true to validate before executing.

⚠ Actions like bgp_hard_reset and reload_port_card are service-impacting. Always test with dry_run: true first.

POST

/v1/actions/execute

Execute an automated remediation action on a device

▶

Field	Type	Required	Description
device_id	string	required	Target device
action_type	enum	required	See `GET /v1/actions/supported` for full list
parameters	object	optional	Action-specific params, e.g. `{"interface": "Gi0/0/1"}`
ticket_id	string	optional	Associated ticket for audit trail
reason	string	required	Reason for execution — stored in audit log
dry_run	boolean	optional	Validate without executing (default: false)

Request — Interface Bounce

        
{
  "device_id": "DEV-MUM-PE01",
  "action_type": "interface_bounce",
  "parameters": { "interface": "Gi0/0/1" },
  "ticket_id": "TKT-20240301-0088",
  "reason": "Link flap recovery — L1 auto-remediation attempt 1",
  "dry_run": false
}
      

Response 202 Accepted

        
{
  "action_id": "ACT-E5F6G7H8",
  "status": "COMPLETED",
  "result": { "interface": "Gi0/0/1", "oper_status_after": "UP", "recovery_time_s": 8 },
  "executed_commands": ["configure", "interface Gi0/0/1", "shutdown", "no shutdown", "commit", "exit"],
  "rollback_available": false
}
      

RCA / RFO

LLM-powered Root Cause Analysis. Correlates alarms, interface telemetry, optical power, and BGP logs to produce a structured RCA and formatted RFO document.

POST

/v1/rca/generate

Generate RCA + RFO for a ticket — AI-correlated, confidence-scored

▶

Field	Type	Required	Description
ticket_id	string	required	The ticket to generate RCA for
time_window_minutes	integer	optional	Event correlation window in minutes (default: 60, max: 1440)
include_optical	boolean	optional	Include DWDM optical telemetry in analysis (default: true)
generate_rfo	boolean	optional	Include formatted RFO document in response (default: true)

Example Response 202 Accepted

        
{
  "rca_id": "RCA-A1B2C3D4",
  "ticket_id": "TKT-20240301-0088",
  "root_cause": "Physical link failure — CPE power outage on CUST-1092 last-mile segment",
  "confidence_pct": 94.5,
  "contributing_factors": [
    "LOS detected on Gi0/0/1 — 142 in-errors before link drop",
    "ICMP ping to CPE 192.168.100.2: 100% packet loss",
    "BGP session dropped 5s after interface DOWN (consequence)"
  ],
  "impact_duration_minutes": 30,
  "affected_customers": ["CUST-1092"],
  "rfo_document": "REASON FOR OUTAGE (RFO)\n========================\n..."
}
      

Escalation

Escalate tickets from L1 to L2/L3 with structured handover notes. Notifications are dispatched via email, Slack, and Freshservice.

POST

/v1/escalation/trigger

Escalate a ticket from L1 → L2 or L2 → L3

▶

Request Body

        
{
  "ticket_id": "TKT-20240301-0088",
  "from_tier": "L1",
  "to_tier": "L2",
  "reason": "Auto-remediation failed after 2 attempts. CPE physically unresponsive.",
  "handover_notes": "Ping: 100% loss. Interface bounce: no recovery. Field visit needed.",
  "urgent": true
}
      

Response 202 Accepted

        
{
  "escalation_id": "ESC-00A1B2C3",
  "assigned_to": "support@d2c.in",
  "notification_sent": true,
  "channels_notified": ["email", "slack", "freshservice"],
  "sla_remaining_seconds": 1500
}
      

Error Handling

All errors return a consistent JSON envelope with HTTP status codes following REST conventions.

Code	Description
200	OK — Request succeeded
201	Created — Resource created successfully
202	Accepted — Async operation initiated (diagnostics, actions, RCA)
400	Bad Request — Invalid parameters or unsupported action type
401	Unauthorized — Missing or invalid Bearer token
403	Forbidden — Insufficient agent permissions for this action
404	Not Found — Device, ticket, or alarm ID does not exist
409	Conflict — Action already in progress on this device
422	Unprocessable — Request body validation failed
500	Internal Server Error — Contact NOC Engineering
503	Service Unavailable — Agent SSH pool or NMS connection down

Error Response Format

    
{
  "error": "device_not_found",
  "detail": "Device DEV-MUM-PE99 not found in inventory",
  "request_id": "req_a1b2c3d4e5f6",
  "timestamp": 1709284800
}
  

Try It

Interactive mock console. Calls https://api.d2c.in/v1 — ensure the server is running locally or replace with your deployment URL.

Network L1 Agent API

Obtain Token

Attach to Requests