Skip to main content

ZTP API Reference

The ZTP (Zero Touch Provisioning) API enables programmatic management of device provisioning manifests, serial number registration, configuration generation, and deployment status monitoring.

Authentication​

All ZTP API endpoints require authentication via API token:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Manifest Management​

List Manifests​

GET /api/v1/ztp/manifests

Query Parameters:

  • site_id (optional): Filter by site identifier
  • status (optional): Filter by manifest status (draft, ready, deploying, deployed)
  • limit (optional): Maximum number of results (default: 50)
  • offset (optional): Pagination offset (default: 0)

Response:

{
  "manifests": [
    {
      "id": "manifest_123",
      "name": "Production Floor A",
      "site_id": "site_456",
      "status": "ready",
      "device_count": 25,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z",
      "topology_source": "helm_topology_789"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Create Manifest​

POST /api/v1/ztp/manifests

Request Body:

{
  "name": "Production Floor B",
  "site_id": "site_456",
  "description": "Manufacturing line 2 network deployment",
  "topology_source": "helm_topology_790",
  "config_templates": {
    "cisco_ie3300": "template_switch_basic",
    "fortigate_60f": "template_firewall_dmz"
  }
}

Response:

{
  "id": "manifest_124",
  "name": "Production Floor B",
  "site_id": "site_456",
  "status": "draft",
  "device_count": 0,
  "created_at": "2024-01-21T09:15:00Z"
}

Get Manifest Details​

GET /api/v1/ztp/manifests/{manifest_id}

Response:

{
  "id": "manifest_123",
  "name": "Production Floor A",
  "site_id": "site_456",
  "status": "ready",
  "device_count": 25,
  "devices": [
    {
      "id": "device_001",
      "hostname": "sw-prod-01",
      "device_type": "cisco_ie3300",
      "mac_address": "00:1A:2B:3C:4D:5E",
      "serial_number": "FDO123456789",
      "ip_address": "192.168.1.10",
      "status": "serial_registered",
      "config_template": "template_switch_basic"
    }
  ],
  "cable_schedule": {
    "connections": 45,
    "generated_at": "2024-01-20T14:45:00Z",
    "download_url": "/api/v1/ztp/manifests/123/cable-schedule.pdf"
  }
}

Update Manifest​

PUT /api/v1/ztp/manifests/{manifest_id}

Request Body:

{
  "name": "Production Floor A - Updated",
  "status": "ready",
  "config_templates": {
    "cisco_ie3300": "template_switch_advanced"
  }
}

Delete Manifest​

DELETE /api/v1/ztp/manifests/{manifest_id}

Response:

{
  "message": "Manifest deleted successfully",
  "id": "manifest_123"
}

Device Management​

List Devices​

GET /api/v1/ztp/devices

Query Parameters:

  • manifest_id (optional): Filter by manifest
  • status (optional): Filter by device status
  • device_type (optional): Filter by device type
  • search (optional): Search by hostname, MAC, or serial number

Response:

{
  "devices": [
    {
      "id": "device_001",
      "manifest_id": "manifest_123",
      "hostname": "sw-prod-01",
      "device_type": "cisco_ie3300",
      "mac_address": "00:1A:2B:3C:4D:5E",
      "serial_number": "FDO123456789",
      "ip_address": "192.168.1.10",
      "status": "online",
      "last_seen": "2024-01-21T10:30:00Z"
    }
  ]
}

Register Device Serial Number​

POST /api/v1/ztp/devices/{device_id}/serial

Request Body:

{
  "serial_number": "FDO123456789",
  "verification_method": "barcode_scan",
  "operator_id": "user_456"
}

Response:

{
  "device_id": "device_001",
  "serial_number": "FDO123456789",
  "status": "serial_registered",
  "verified_at": "2024-01-21T11:00:00Z",
  "model_detected": "IE-3300-8T2S-E"
}

Bulk Serial Registration​

POST /api/v1/ztp/devices/bulk-serial

Request Body:

{
  "manifest_id": "manifest_123",
  "serials": [
    {
      "device_id": "device_001",
      "serial_number": "FDO123456789"
    },
    {
      "device_id": "device_002", 
      "serial_number": "FDO987654321"
    }
  ],
  "verification_method": "csv_import",
  "operator_id": "user_456"
}

Response:

{
  "processed": 2,
  "successful": 2,
  "failed": 0,
  "results": [
    {
      "device_id": "device_001",
      "status": "success",
      "serial_number": "FDO123456789"
    },
    {
      "device_id": "device_002",
      "status": "success",
      "serial_number": "FDO987654321"
    }
  ]
}

Configuration Management​

Generate Device Configurations​

POST /api/v1/ztp/manifests/{manifest_id}/generate-configs

Request Body:

{
  "device_ids": ["device_001", "device_002"],
  "force_regenerate": false
}

Response:

{
  "job_id": "config_job_789",
  "status": "processing",
  "devices_queued": 2,
  "estimated_completion": "2024-01-21T11:15:00Z"
}

Get Device Configuration​

GET /api/v1/ztp/devices/{device_id}/config

Query Parameters:

  • format (optional): text or json (default: text)

Response:

{
  "device_id": "device_001",
  "config_generated_at": "2024-01-21T11:10:00Z",
  "format": "text",
  "content": "!\n! Cisco IE-3300 Configuration\n! Generated by Breakwater ZTP\n!\nversion 16.12\n...",
  "template_used": "template_switch_basic",
  "size_bytes": 2048
}

Template Management​

List Configuration Templates​

GET /api/v1/ztp/templates

Query Parameters:

  • device_type (optional): Filter by device type
  • category (optional): Filter by template category

Response:

{
  "templates": [
    {
      "id": "template_switch_basic",
      "name": "Cisco IE Basic Switch Config",
      "device_type": "cisco_ie3300",
      "category": "network_switch",
      "version": "1.2",
      "variables": [
        {
          "name": "hostname",
          "type": "string",
          "required": true
        },
        {
          "name": "vlan_list",
          "type": "array",
          "required": false
        }
      ]
    }
  ]
}

Status and Monitoring​

Get ZTP System Status​

GET /api/v1/ztp/status

Response:

{
  "system_status": "operational",
  "active_deployments": 3,
  "queue_depth": 12,
  "success_rate_24h": 97.5,
  "average_deployment_time": "00:08:30",
  "last_deployment": "2024-01-21T10:45:00Z"
}

Get Deployment Events​

GET /api/v1/ztp/events

Query Parameters:

  • manifest_id (optional): Filter by manifest
  • device_id (optional): Filter by device
  • event_type (optional): Filter by event type
  • start_date (optional): Start date for event range
  • end_date (optional): End date for event range

Response:

{
  "events": [
    {
      "id": "event_123",
      "timestamp": "2024-01-21T11:00:00Z",
      "event_type": "serial_registered",
      "device_id": "device_001",
      "manifest_id": "manifest_123",
      "details": {
        "serial_number": "FDO123456789",
        "operator_id": "user_456",
        "verification_method": "barcode_scan"
      }
    },
    {
      "id": "event_124",
      "timestamp": "2024-01-21T11:10:00Z",
      "event_type": "config_generated",
      "device_id": "device_001",
      "manifest_id": "manifest_123",
      "details": {
        "template_id": "template_switch_basic",
        "config_size": 2048
      }
    }
  ]
}

Error Handling​

Standard Error Response​

{
  "error": {
    "code": "INVALID_MANIFEST_STATUS",
    "message": "Cannot deploy manifest in draft status",
    "details": {
      "manifest_id": "manifest_123",
      "current_status": "draft",
      "required_status": "ready"
    }
  }
}

Common Error Codes​

  • MANIFEST_NOT_FOUND: Manifest ID does not exist
  • DEVICE_NOT_FOUND: Device ID does not exist
  • INVALID_SERIAL_NUMBER: Serial number format invalid
  • SERIAL_ALREADY_REGISTERED: Serial number already in use
  • CONFIG_GENERATION_FAILED: Template processing error
  • DEPLOYMENT_IN_PROGRESS: Cannot modify during active deployment
  • INSUFFICIENT_PERMISSIONS: API token lacks required permissions