{ "openapi": "3.0.1", "info": { "title": "Cisco Meraki Dashboard API \u2014 devices", "description": "The devices operations of the Cisco Meraki Dashboard API, split by product area from Cisco's published OpenAPI definition.", "version": "1.72.0", "contact": { "name": "Meraki Developer Community", "url": "https://meraki.io/community" }, "x-provenance": { "method": "harvested", "authored_by": "Cisco Meraki", "harvested_by": "API Evangelist", "harvested_on": "2026-07-31", "first_party": true, "note": "Split by first tag from Cisco's published spec3.json; operations unmodified.", "provider_published": true }, "x-evidence": [ { "type": "source", "url": "https://github.com/meraki/openapi/blob/master/openapi/spec3.json" }, { "type": "raw", "url": "https://raw.githubusercontent.com/meraki/openapi/master/openapi/spec3.json" }, { "type": "alternate", "url": "https://api.meraki.com/api/v1/openapiSpec" } ] }, "servers": [ { "url": "https://api.meraki.com/{basePath}", "variables": { "basePath": { "default": "api/v1" } } } ], "security": [ { "meraki_api_key": [] }, { "bearerAuth": [] } ], "tags": [ { "name": "arpTable", "description": "" }, { "name": "bands", "description": "" }, { "name": "blink", "description": "" }, { "name": "cableTest", "description": "" }, { "name": "cellular", "description": "" }, { "name": "clients", "description": "" }, { "name": "configure", "description": "" }, { "name": "cycle", "description": "" }, { "name": "devices", "description": "" }, { "name": "geolocations", "description": "" }, { "name": "leds", "description": "" }, { "name": "liveTools", "description": "" }, { "name": "lldpCdp", "description": "" }, { "name": "lookups", "description": "" }, { "name": "lossAndLatencyHistory", "description": "" }, { "name": "macTable", "description": "" }, { "name": "managementInterface", "description": "" }, { "name": "masks", "description": "" }, { "name": "monitor", "description": "" }, { "name": "multicastRouting", "description": "" }, { "name": "ping", "description": "" }, { "name": "pingDevice", "description": "" }, { "name": "ports", "description": "" }, { "name": "power", "description": "" }, { "name": "routingTable", "description": "" }, { "name": "sims", "description": "" }, { "name": "status", "description": "" }, { "name": "summaries", "description": "" }, { "name": "throughputTest", "description": "" }, { "name": "update", "description": "" }, { "name": "uplinks", "description": "" }, { "name": "usage", "description": "" }, { "name": "wakeOnLan", "description": "" } ], "components": { "securitySchemes": { "meraki_api_key": { "type": "apiKey", "name": "X-Cisco-Meraki-API-Key", "in": "header" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } } }, "paths": { "/devices/{serial}": { "get": { "description": "Return a single device", "operationId": "getDevice", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the device" }, "lat": { "type": "number", "format": "float", "description": "Latitude of the device" }, "lng": { "type": "number", "format": "float", "description": "Longitude of the device" }, "address": { "type": "string", "description": "Physical address of the device" }, "notes": { "type": "string", "description": "Notes for the device, limited to 255 characters" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "List of tags assigned to the device" }, "networkId": { "type": "string", "description": "ID of the network the device belongs to" }, "serial": { "type": "string", "description": "Serial number of the device" }, "model": { "type": "string", "description": "Model of the device" }, "mac": { "type": "string", "description": "MAC address of the device" }, "lanIp": { "type": "string", "description": "LAN IP address of the device" }, "firmware": { "type": "string", "description": "Firmware version of the device" }, "floorPlanId": { "type": "string", "description": "The floor plan to associate to this device. null disassociates the device from the floorplan.", "nullable": true }, "url": { "type": "string", "description": "URL link to the device in the Meraki Dashboard" }, "details": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Additional property name" }, "value": { "type": "string", "description": "Additional property value" } } }, "description": "Additional device information" }, "beaconIdParams": { "type": "object", "properties": { "uuid": { "type": "string", "description": "The UUID to be used in the beacon identifier" }, "major": { "type": "integer", "description": "The major number to be used in the beacon identifier" }, "minor": { "type": "integer", "description": "The minor number to be used in the beacon identifier" } }, "description": "Beacon Id parameters with an identifier and major and minor versions" } } }, "example": { "name": "My AP", "lat": 37.4180951010362, "lng": -122.098531723022, "address": "1600 Pennsylvania Ave", "notes": "My AP's note", "tags": [ " recently-added " ], "networkId": "N_24329156", "serial": "Q234-ABCD-5678", "model": "MR34", "mac": "00:11:22:33:44:55", "lanIp": "1.2.3.4", "firmware": "wireless-25-14", "floorPlanId": "g_2176982374", "url": "https://n1.meraki.com/MyOrg/n/XXXXXX/manage/nodes/new_list/1", "details": [ { "name": "Catalyst serial", "value": "123ABC" } ], "beaconIdParams": { "uuid": "00000000-0000-0000-0000-000000000000", "major": 5, "minor": 3 } } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:read" ] } ], "summary": "Return a single device", "tags": [ "devices", "configure" ] }, "put": { "description": "Update the attributes of a device", "operationId": "updateDevice", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "The name of a device" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "The list of tags of a device" }, "lat": { "type": "number", "format": "float", "description": "The latitude of a device" }, "lng": { "type": "number", "format": "float", "description": "The longitude of a device" }, "address": { "type": "string", "nullable": true, "description": "The address of a device" }, "notes": { "type": "string", "nullable": true, "description": "The notes for the device. String. Limited to 255 characters." }, "moveMapMarker": { "type": "boolean", "description": "Whether or not to set the latitude and longitude of a device based on the new address. Only applies when lat and lng are not specified." }, "switchProfileId": { "type": "string", "nullable": true, "description": "The ID of a switch template to bind to the device (for available switch templates, see the 'Switch Templates' endpoint). Use null to unbind the switch device from the current profile. For a device to be bindable to a switch template, it must (1) be a switch, and (2) belong to a network that is bound to a configuration template." }, "floorPlanId": { "type": "string", "nullable": true, "description": "The floor plan to associate to this device. null disassociates the device from the floorplan." } }, "example": { "name": "My AP", "tags": [ " recently-added " ], "lat": 37.4180951010362, "lng": -122.098531723022, "address": "1600 Pennsylvania Ave", "notes": "My AP's note", "moveMapMarker": true, "switchProfileId": "1234", "floorPlanId": "g_2176982374" } } } }, "required": false }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the device" }, "lat": { "type": "number", "format": "float", "description": "Latitude of the device" }, "lng": { "type": "number", "format": "float", "description": "Longitude of the device" }, "address": { "type": "string", "description": "Physical address of the device" }, "notes": { "type": "string", "description": "Notes for the device, limited to 255 characters" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "List of tags assigned to the device" }, "networkId": { "type": "string", "description": "ID of the network the device belongs to" }, "serial": { "type": "string", "description": "Serial number of the device" }, "model": { "type": "string", "description": "Model of the device" }, "mac": { "type": "string", "description": "MAC address of the device" }, "lanIp": { "type": "string", "description": "LAN IP address of the device" }, "firmware": { "type": "string", "description": "Firmware version of the device" }, "floorPlanId": { "type": "string", "description": "The floor plan to associate to this device. null disassociates the device from the floorplan.", "nullable": true }, "url": { "type": "string", "description": "URL link to the device in the Meraki Dashboard" }, "details": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Additional property name" }, "value": { "type": "string", "description": "Additional property value" } } }, "description": "Additional device information" }, "beaconIdParams": { "type": "object", "properties": { "uuid": { "type": "string", "description": "The UUID to be used in the beacon identifier" }, "major": { "type": "integer", "description": "The major number to be used in the beacon identifier" }, "minor": { "type": "integer", "description": "The minor number to be used in the beacon identifier" } }, "description": "Beacon Id parameters with an identifier and major and minor versions" } } }, "example": { "name": "My AP", "lat": 37.4180951010362, "lng": -122.098531723022, "address": "1600 Pennsylvania Ave", "notes": "My AP's note", "tags": [ " recently-added " ], "networkId": "N_24329156", "serial": "Q234-ABCD-5678", "model": "MR34", "mac": "00:11:22:33:44:55", "lanIp": "1.2.3.4", "firmware": "wireless-25-14", "floorPlanId": "g_2176982374", "url": "https://n1.meraki.com/MyOrg/n/XXXXXX/manage/nodes/new_list/1", "details": [ { "name": "Catalyst serial", "value": "123ABC" } ], "beaconIdParams": { "uuid": "00000000-0000-0000-0000-000000000000", "major": 5, "minor": 3 } } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:write" ] } ], "summary": "Update the attributes of a device", "tags": [ "devices", "configure" ] } }, "/devices/{serial}/blinkLeds": { "post": { "deprecated": true, "description": "Blink the LEDs on a device. This endpoint is deprecrated in favor of \"/devices/{serial}/liveTools/leds/blink\".", "operationId": "blinkDeviceLeds", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "duration": { "type": "integer", "description": "The duration in seconds. Must be between 5 and 120. Default is 20 seconds" }, "period": { "type": "integer", "description": "The period in milliseconds. Must be between 100 and 1000. Default is 160 milliseconds" }, "duty": { "type": "integer", "description": "The duty cycle as the percent active. Must be between 10 and 90. Default is 50." } }, "example": { "duration": 20, "period": 160, "duty": 50 } } } }, "required": false }, "responses": { "202": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "duration": { "type": "integer", "description": "The duration in seconds. Will be between 5 and 120. Default is 20 seconds" }, "period": { "type": "integer", "description": "The period in milliseconds. Will be between 100 and 1000. Default is 160 milliseconds" }, "duty": { "type": "integer", "description": "The duty cycle as the percent active. Will be between 10 and 90. Default is 50" } } }, "example": { "duration": 20, "period": 160, "duty": 50 } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:write" ] } ], "summary": "Blink the LEDs on a device", "tags": [ "devices", "liveTools" ], "x-deprecation-notice": "Deprecated: This operation has been marked as deprecated. For more information, visit the deprecated operations page" } }, "/devices/{serial}/cellular/geolocations": { "put": { "description": "Update the enablement of the geolocation feature for a device", "operationId": "updateDeviceCellularGeolocations", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Required parameter for the state to update the geolocation settings to (true to enable, false to disable)" } }, "example": { "enabled": true }, "required": [ "enabled" ] } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Indicates whether geolocation is enabled for the device" } } }, "example": { "enabled": true } } } } }, "summary": "Update the enablement of the geolocation feature for a device", "tags": [ "devices", "configure", "cellular", "geolocations" ] } }, "/devices/{serial}/cellular/sims": { "get": { "description": "Return the SIM and APN configurations for a cellular device.", "operationId": "getDeviceCellularSims", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "sims": { "type": "array", "items": { "type": "object", "properties": { "slot": { "type": "string", "description": "SIM slot being configured. Must be 'sim1' on single-sim devices. eSIM slots use the raw slot value for the device, such as 'sim2' or 'sim3'." }, "iccid": { "type": "string", "description": "Integrated Circuit Card Identification Number" }, "imsi": { "type": "string", "description": "International Mobile Subscriber Identity" }, "msisdn": { "type": "string", "description": "Mobile Station Integrated Services Digital Network" }, "isPrimary": { "type": "boolean", "description": "If true, this SIM is activated on platform bootup. It must be true on single-SIM devices and is a required field for dual-SIM MGs unless it is being configured using 'simOrdering'.", "default": false }, "status": { "type": "string", "enum": [ "PIN required", "PUK required", "active", "inserted", "not inserted", "standby", "unknown" ], "description": "Status of the SIM card." }, "apns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "APN name." }, "allowedIpTypes": { "type": "array", "items": { "type": "string" }, "description": "IP versions to support (permitted values include 'ipv4', 'ipv6')." }, "authentication": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "chap", "none", "pap" ], "description": "APN auth type.", "default": "none" }, "username": { "type": "string", "description": "APN username, if type is set." }, "password": { "type": "string", "description": "APN password, if type is set (if APN password is not supplied, the password is left unchanged)." } }, "description": "APN authentication configurations." } }, "required": [ "name", "allowedIpTypes" ] }, "description": "APN configurations. If empty, the default APN will be used.", "default": [] } } }, "description": "List of SIMs. If a SIM was previously configured and not specified in this request, it will remain unchanged." }, "simOrdering": { "type": "array", "items": { "type": "string" }, "description": "Specifies the ordering of all SIMs for an MG: primary, secondary, and not-in-use (when applicable). It's required for devices with 3 or more SIMs and can be used in place of 'isPrimary' for dual-SIM devices. Use the raw eSIM slot value for the device, such as 'sim2' or 'sim3'. Sim failover will occur only between primary and secondary sim slots." }, "simFailover": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Failover to secondary SIM" }, "timeout": { "type": "integer", "description": "Failover timeout in seconds" } }, "description": "SIM Failover settings." } } }, "example": { "sims": [ { "slot": "sim1", "iccid": "123456789", "imsi": "123456789012345", "msisdn": "123456789012345", "isPrimary": false, "status": "inserted", "apns": [ { "name": "internet", "allowedIpTypes": [ "ipv4", "ipv6" ], "authentication": { "type": "pap", "username": "milesmeraki", "password": "secret" } } ] } ], "simOrdering": [ "sim1", "sim2", "sim3" ], "simFailover": { "enabled": true, "timeout": 300 } } } } } }, "security": [ { "oauth2": [ "sdwan:config:read" ] } ], "summary": "Return the SIM and APN configurations for a cellular device.", "tags": [ "devices", "configure", "cellular", "sims" ] }, "put": { "description": "Updates the SIM and APN configurations for a cellular device.", "operationId": "updateDeviceCellularSims", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sims": { "type": "array", "items": { "type": "object", "properties": { "slot": { "type": "string", "description": "SIM slot being configured. Must be 'sim1' on single-sim devices. eSIM slots use the raw slot value for the device, such as 'sim2' or 'sim3'." }, "isPrimary": { "type": "boolean", "description": "If true, this SIM is activated on platform bootup. It must be true on single-SIM devices and is a required field for dual-SIM MGs unless it is being configured using 'simOrdering'.", "default": false }, "apns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "APN name." }, "allowedIpTypes": { "type": "array", "items": { "type": "string" }, "description": "IP versions to support (permitted values include 'ipv4', 'ipv6')." }, "authentication": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "chap", "none", "pap" ], "description": "APN auth type.", "default": "none" }, "username": { "type": "string", "description": "APN username, if type is set." }, "password": { "type": "string", "description": "APN password, if type is set (if APN password is not supplied, the password is left unchanged)." } }, "description": "APN authentication configurations." } }, "required": [ "name", "allowedIpTypes" ] }, "description": "APN configurations. If empty, the default APN will be used." }, "simOrder": { "type": "integer", "description": "Priority of SIM slot being configured. Use a value between 1 and total number of SIMs available. The value must be unique for each SIM." } } }, "description": "List of SIMs. If a SIM was previously configured and not specified in this request, it will remain unchanged." }, "simOrdering": { "type": "array", "items": { "type": "string" }, "description": "Specifies the ordering of all SIMs for an MG: primary, secondary, and not-in-use (when applicable). It's required for devices with 3 or more SIMs and can be used in place of 'isPrimary' for dual-SIM devices. Use the raw eSIM slot value for the device, such as 'sim2' or 'sim3'. Sim failover will occur only between primary and secondary sim slots." }, "simFailover": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Failover to secondary SIM (optional)" }, "timeout": { "type": "integer", "description": "Failover timeout in seconds (optional)", "nullable": true } }, "description": "SIM Failover settings." } }, "example": { "sims": [ { "slot": "sim1", "isPrimary": false, "apns": [ { "name": "internet", "allowedIpTypes": [ "ipv4", "ipv6" ], "authentication": { "type": "pap", "username": "milesmeraki", "password": "secret" } } ], "simOrder": 3 } ], "simOrdering": [ "sim1", "sim2", "sim3" ], "simFailover": { "enabled": true, "timeout": 300 } } } } }, "required": false }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "sims": { "type": "array", "items": { "type": "object", "properties": { "slot": { "type": "string", "description": "SIM slot being configured. Must be 'sim1' on single-sim devices. eSIM slots use the raw slot value for the device, such as 'sim2' or 'sim3'." }, "iccid": { "type": "string", "description": "Integrated Circuit Card Identification Number" }, "imsi": { "type": "string", "description": "International Mobile Subscriber Identity" }, "msisdn": { "type": "string", "description": "Mobile Station Integrated Services Digital Network" }, "isPrimary": { "type": "boolean", "description": "If true, this SIM is activated on platform bootup. It must be true on single-SIM devices and is a required field for dual-SIM MGs unless it is being configured using 'simOrdering'.", "default": false }, "status": { "type": "string", "enum": [ "PIN required", "PUK required", "active", "inserted", "not inserted", "standby", "unknown" ], "description": "Status of the SIM card." }, "apns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "APN name." }, "allowedIpTypes": { "type": "array", "items": { "type": "string" }, "description": "IP versions to support (permitted values include 'ipv4', 'ipv6')." }, "authentication": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "chap", "none", "pap" ], "description": "APN auth type.", "default": "none" }, "username": { "type": "string", "description": "APN username, if type is set." }, "password": { "type": "string", "description": "APN password, if type is set (if APN password is not supplied, the password is left unchanged)." } }, "description": "APN authentication configurations." } }, "required": [ "name", "allowedIpTypes" ] }, "description": "APN configurations. If empty, the default APN will be used.", "default": [] } } }, "description": "List of SIMs. If a SIM was previously configured and not specified in this request, it will remain unchanged." }, "simOrdering": { "type": "array", "items": { "type": "string" }, "description": "Specifies the ordering of all SIMs for an MG: primary, secondary, and not-in-use (when applicable). It's required for devices with 3 or more SIMs and can be used in place of 'isPrimary' for dual-SIM devices. Use the raw eSIM slot value for the device, such as 'sim2' or 'sim3'. Sim failover will occur only between primary and secondary sim slots." }, "simFailover": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Failover to secondary SIM" }, "timeout": { "type": "integer", "description": "Failover timeout in seconds" } }, "description": "SIM Failover settings." } } }, "example": { "sims": [ { "slot": "sim1", "iccid": "123456789", "imsi": "123456789012345", "msisdn": "123456789012345", "isPrimary": false, "status": "inserted", "apns": [ { "name": "internet", "allowedIpTypes": [ "ipv4", "ipv6" ], "authentication": { "type": "pap", "username": "milesmeraki", "password": "secret" } } ] } ], "simOrdering": [ "sim1", "sim2", "sim3" ], "simFailover": { "enabled": true, "timeout": 300 } } } } } }, "security": [ { "oauth2": [ "sdwan:config:write" ] } ], "summary": "Updates the SIM and APN configurations for a cellular device.", "tags": [ "devices", "configure", "cellular", "sims" ] } }, "/devices/{serial}/cellular/uplinks/bands/masks/update": { "post": { "description": "Update the cellular band masks for a device", "operationId": "createDeviceCellularUplinksBandsMasksUpdate", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "sim1", "sim2", "sim3" ], "description": "Required parameter for the SIM slot to update the cellular band mask for" }, "type": { "type": "string", "enum": [ "5GNSA", "5GSA", "LTE" ], "description": "Required parameter for the signal type to update the cellular band mask for" }, "masked": { "type": "array", "items": { "type": "string" }, "description": "Required parameter for the band identifiers to mask for the given SIM slot and signal type. For LTE use bands identifiers like '30', for 5G use band identifiers like 'n30', or use 'all' to mask all bands for that signal type. Maximum 256 bands." } }, "example": { "slot": "sim1", "type": "LTE", "masked": [ "2", "12", "30" ] }, "required": [ "slot", "type", "masked" ] } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "bySlot": { "type": "array", "items": { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "sim1", "sim2", "sim3" ], "description": "SIM slot identifier" }, "bySignalType": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "5GNSA", "5GSA", "LTE" ], "description": "Cellular connection type" }, "masked": { "type": "array", "items": { "type": "string" }, "description": "List of masked band identifiers. For LTE use bands identifiers like '30', for 5G use band identifiers like 'n30', or 'all' when all bands are masked. Maximum 256 bands per signal type." }, "enabled": { "type": "array", "items": { "type": "string" }, "description": "List of enabled band identifiers. For LTE use bands identifiers like '30' and for 5G use band identifiers like 'n30'. Maximum 256 bands per signal type." }, "supported": { "type": "array", "items": { "type": "string" }, "description": "List of supported band identifiers. For LTE use bands identifiers like '30' and for 5G use band identifiers like 'n30'. Maximum 256 bands per signal type." } } }, "description": "Signal settings for the SIM. Maximum 3 signal types per SIM slot." } } }, "description": "SIMs associated with the device. Maximum 3 SIM slots per device." } } }, "example": { "bySlot": [ { "slot": "sim1", "bySignalType": [ { "type": "LTE", "masked": [ "2", "12", "30" ], "enabled": [ "8", "10" ], "supported": [ "2", "4", "8", "10", "12" ] } ] } ] } } } } }, "summary": "Update the cellular band masks for a device", "tags": [ "devices", "configure", "cellular", "uplinks", "bands", "masks", "update" ] } }, "/devices/{serial}/clients": { "get": { "description": "List the clients of a device, up to a maximum of a month ago. The usage of each client is returned in kilobytes. If the device is a switch, the switchport is returned; otherwise the switchport field is null.", "operationId": "getDeviceClients", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "t0", "in": "query", "description": "The beginning of the timespan for the data. The maximum lookback period is 31 days from today.", "schema": { "type": "string" } }, { "name": "timespan", "in": "query", "description": "The timespan for which the information will be fetched. If specifying timespan, do not specify parameter t0. The value must be in seconds and be less than or equal to 31 days. The default is 1 day.", "schema": { "type": "number", "format": "float", "maximum": 2678400 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the client" }, "mac": { "type": "string", "description": "The MAC address of the client" }, "description": { "type": "string", "description": "Short description of the client" }, "mdnsName": { "type": "string", "description": "The client's MDNS name" }, "dhcpHostname": { "type": "string", "description": "The client's DHCP hostname" }, "user": { "type": "string", "description": "The client user's name" }, "ip": { "type": "string", "description": "The IP address of the client" }, "vlan": { "type": "string", "description": "The client-assigned name of the VLAN the client is connected to" }, "namedVlan": { "type": "string", "description": "The owner-assigned name of the VLAN the client is connected to" }, "switchport": { "type": "string", "description": "The name of the switchport with clients on it, if the device is a switch" }, "adaptivePolicyGroup": { "type": "string", "description": "A description of the adaptive policy group" }, "usage": { "type": "object", "properties": { "sent": { "type": "number", "format": "float", "description": "Usage sent by the client" }, "recv": { "type": "number", "format": "float", "description": "Usage received by the client" } }, "description": "Client usage data for sent and received" } } } }, "example": [ { "id": "k74272e", "mac": "22:33:44:55:66:77", "description": "Miles's phone", "mdnsName": "Miles's phone", "dhcpHostname": "MilesPhone", "user": "milesmeraki", "ip": "1.2.3.4", "vlan": "100", "namedVlan": "My VLAN", "switchport": "My switch port", "adaptivePolicyGroup": "101", "usage": { "sent": 138.0, "recv": 61.0 } } ] } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:read" ] } ], "summary": "List the clients of a device, up to a maximum of a month ago", "tags": [ "devices", "monitor", "clients" ] } }, "/devices/{serial}/liveTools/arpTable": { "post": { "callbacks": { "arpTable": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "arpTableId": { "type": "string", "description": "Id of the ARP table request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your ARP table request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "ARP table request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the ARP table request." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string", "description": "The IP address of the ARP table entry" }, "mac": { "type": "string", "description": "The MAC address of the ARP table entry" }, "vlanId": { "type": "integer", "description": "The VLAN ID of the ARP table entry. Null for Meraki wireless devices.", "x-nullable": true }, "interface": { "type": "string", "description": "The interface name of the ARP table entry, such as Vlan1, Port-channel2, or GigabitEthernet1/0/1" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "Time of the last update of the ARP table entry. Null for Meraki wireless devices.", "x-nullable": true } } }, "description": "The ARP table entries" }, "error": { "type": "string", "description": "An error message for a failed execution" } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to perform a ARP table request for the device. This endpoint currently supports switches, wireless access points, and catalyst routers. This endpoint has a sustained rate limit of one request every five seconds per device, with an allowed burst of five requests.", "operationId": "createDeviceLiveToolsArpTable", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } } } } }, "required": false }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "arpTableId": { "type": "string", "description": "Id of the ARP table request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your ARP table request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "ARP table request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the ARP table request." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "arpTableId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/arpTable/1284392014819", "request": { "serial": "Q234-ABCD-5678" }, "status": "complete", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:write" ] } ], "summary": "Enqueue a job to perform a ARP table request for the device", "tags": [ "devices", "liveTools", "arpTable" ] } }, "/devices/{serial}/liveTools/arpTable/{arpTableId}": { "get": { "description": "Return an ARP table live tool job.", "operationId": "getDeviceLiveToolsArpTable", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "arpTableId", "in": "path", "description": "Arp table ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "arpTableId": { "type": "string", "description": "Id of the ARP table request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your ARP table request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "ARP table request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the ARP table request." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string", "description": "The IP address of the ARP table entry" }, "mac": { "type": "string", "description": "The MAC address of the ARP table entry" }, "vlanId": { "type": "integer", "description": "The VLAN ID of the ARP table entry. Null for Meraki wireless devices.", "nullable": true }, "interface": { "type": "string", "description": "The interface name of the ARP table entry, such as Vlan1, Port-channel2, or GigabitEthernet1/0/1" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "Time of the last update of the ARP table entry. Null for Meraki wireless devices.", "nullable": true } } }, "description": "The ARP table entries" }, "error": { "type": "string", "description": "An error message for a failed execution" } } }, "example": { "arpTableId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/arpTable/1284392014819", "request": { "serial": "Q234-ABCD-5678" }, "status": "complete", "entries": [ { "ip": "10.0.0.0/24", "mac": "00:11:22:33:44:55", "vlanId": 100, "interface": "Vlan100", "lastUpdatedAt": "2018-02-11T00:00:00.090210Z" } ], "error": "The device is unreachable." } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:read" ] } ], "summary": "Return an ARP table live tool job.", "tags": [ "devices", "liveTools", "arpTable" ] } }, "/devices/{serial}/liveTools/cableTest": { "post": { "callbacks": { "cableTest": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "cableTestId": { "type": "string", "description": "Id of the cable test request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your cable test request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "ports": { "type": "array", "items": { "type": "string" }, "description": "A list of ports for which to perform the cable test." } }, "description": "Cable test request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the cable test request." }, "results": { "type": "array", "items": { "type": "object", "properties": { "port": { "type": "string", "description": "The port for which the test was performed." }, "status": { "type": "string", "enum": [ "down", "error", "in-progress", "up" ], "description": "The current status of the port. If the cable test is still being performed on the port, \"in-progress\" is used. If an error occurred during the cable test, \"error\" is used and the error property will be populated." }, "speedMbps": { "type": "integer", "description": "Speed in Mbps. A speed of 0 indicates the port is down or the port speed is automatic." }, "error": { "type": "string", "description": "If an error occurred during the cable test, the error message will be populated here." }, "pairs": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "description": "The index of the twisted pair tested." }, "status": { "type": "string", "enum": [ "abnormal", "couplex", "fail", "forced", "in-progress", "invalid", "not-supported", "ok", "open", "open or short", "short", "short or abnormal", "short or couplex", "unknown" ], "description": "The test result of the twisted pair tested." }, "lengthMeters": { "type": "integer", "description": "The detected length of the twisted pair." } } }, "description": "Results for each twisted pair within the cable." } } }, "description": "Results of the cable test request, one for each requested port." }, "error": { "type": "string", "description": "An error message for a failed execution" } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to perform a cable test for the device on the specified ports. This endpoint has a sustained rate limit of one request every five seconds per device, with an allowed burst of five requests.", "operationId": "createDeviceLiveToolsCableTest", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ports": { "type": "array", "items": { "type": "string" }, "description": "A list of ports for which to perform the cable test. For Catalyst switches, IOS interface names are also supported, such as \"GigabitEthernet1/0/8\", \"Gi1/0/8\", or even \"1/0/8\"." }, "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "ports": [ "2", "8" ], "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } }, "required": [ "ports" ] } } }, "required": true }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "cableTestId": { "type": "string", "description": "Id of the cable test request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your cable test request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "ports": { "type": "array", "items": { "type": "string" }, "description": "A list of ports for which to perform the cable test." } }, "description": "Cable test request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the cable test request." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "cableTestId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/cableTest/1284392014819", "request": { "serial": "Q234-ABCD-5678", "ports": [ "2", "8" ] }, "status": "complete", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:write" ] } ], "summary": "Enqueue a job to perform a cable test for the device on the specified ports", "tags": [ "devices", "liveTools", "cableTest" ] } }, "/devices/{serial}/liveTools/cableTest/{id}": { "get": { "description": "Return a cable test live tool job.", "operationId": "getDeviceLiveToolsCableTest", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "path", "description": "ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "cableTestId": { "type": "string", "description": "Id of the cable test request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your cable test request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "ports": { "type": "array", "items": { "type": "string" }, "description": "A list of ports for which to perform the cable test." } }, "description": "Cable test request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the cable test request." }, "results": { "type": "array", "items": { "type": "object", "properties": { "port": { "type": "string", "description": "The port for which the test was performed." }, "status": { "type": "string", "enum": [ "down", "error", "in-progress", "up" ], "description": "The current status of the port. If the cable test is still being performed on the port, \"in-progress\" is used. If an error occurred during the cable test, \"error\" is used and the error property will be populated." }, "speedMbps": { "type": "integer", "description": "Speed in Mbps. A speed of 0 indicates the port is down or the port speed is automatic." }, "error": { "type": "string", "description": "If an error occurred during the cable test, the error message will be populated here." }, "pairs": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "description": "The index of the twisted pair tested." }, "status": { "type": "string", "enum": [ "abnormal", "couplex", "fail", "forced", "in-progress", "invalid", "not-supported", "ok", "open", "open or short", "short", "short or abnormal", "short or couplex", "unknown" ], "description": "The test result of the twisted pair tested." }, "lengthMeters": { "type": "integer", "description": "The detected length of the twisted pair." } } }, "description": "Results for each twisted pair within the cable." } } }, "description": "Results of the cable test request, one for each requested port." }, "error": { "type": "string", "description": "An error message for a failed execution" } } }, "example": { "cableTestId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/cableTest/1284392014819", "request": { "serial": "Q234-ABCD-5678", "ports": [ "2", "8" ] }, "status": "complete", "results": [ { "port": "2", "status": "up", "speedMbps": 10000, "error": "An unexpected error occurred during the execution of the cable test.", "pairs": [ { "index": 0, "status": "ok", "lengthMeters": 1 } ] } ], "error": "The device is unreachable." } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:read" ] } ], "summary": "Return a cable test live tool job.", "tags": [ "devices", "liveTools", "cableTest" ] } }, "/devices/{serial}/liveTools/leds/blink": { "post": { "callbacks": { "ledsBlink": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "ledsBlinkId": { "type": "string", "description": "ID of led blink job" }, "url": { "type": "string", "description": "GET this url to check the status of your leds blink request" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the leds blink request" }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "duration": { "type": "integer", "description": "The duration to blink leds in seconds" } }, "description": "The parameters of the leds blink request" }, "error": { "type": "string", "description": "An error message for a failed Blink LEDs execution, if present" } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to blink LEDs on a device. This endpoint has a rate limit of one request every 10 seconds.", "operationId": "createDeviceLiveToolsLedsBlink", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "duration": { "type": "integer", "description": "The duration in seconds to blink LEDs." }, "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "duration": 30, "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } }, "required": [ "duration" ] } } }, "required": true }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ledsBlinkId": { "type": "string", "description": "ID of led blink job" }, "url": { "type": "string", "description": "GET this url to check the status of your leds blink request" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the leds blink request" }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "duration": { "type": "integer", "description": "The duration to blink leds in seconds" } }, "description": "The parameters of the leds blink request" }, "error": { "type": "string", "description": "An error message for a failed Blink LEDs execution, if present" }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "ledsBlinkId": "123", "url": "/devices/QXXX-YYYY-ZZZZ/liveTools/leds/blink/1738", "status": "complete", "request": { "serial": "Q234-ABCD-5678", "duration": 30 }, "error": "error description", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:write" ] } ], "summary": "Enqueue a job to blink LEDs on a device", "tags": [ "devices", "liveTools", "leds", "blink" ] } }, "/devices/{serial}/liveTools/leds/blink/{ledsBlinkId}": { "get": { "description": "Return a blink LEDs job", "operationId": "getDeviceLiveToolsLedsBlink", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "ledsBlinkId", "in": "path", "description": "Leds blink ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ledsBlinkId": { "type": "string", "description": "ID of led blink job" }, "url": { "type": "string", "description": "GET this url to check the status of your leds blink request" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the leds blink request" }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "duration": { "type": "integer", "description": "The duration to blink leds in seconds" } }, "description": "The parameters of the leds blink request" }, "error": { "type": "string", "description": "An error message for a failed Blink LEDs execution, if present" } } }, "example": { "ledsBlinkId": "123", "url": "/devices/QXXX-YYYY-ZZZZ/liveTools/leds/blink/1738", "status": "complete", "request": { "serial": "Q234-ABCD-5678", "duration": 30 }, "error": "error description" } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:read" ] } ], "summary": "Return a blink LEDs job", "tags": [ "devices", "liveTools", "leds", "blink" ] } }, "/devices/{serial}/liveTools/macTable": { "post": { "callbacks": { "macTable": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "macTableId": { "type": "string", "description": "ID of the MAC table request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your MAC table request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "MAC table request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the MAC table request." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "mac": { "type": "string", "description": "The MAC address of the MAC entry" }, "port": { "type": "string", "description": "The name of the interface of the MAC entry" }, "vlanId": { "type": "integer", "description": "The vlan id of the MAC entry" } } }, "description": "MAC address table entries" }, "error": { "type": "string", "description": "An error message for a failed execution" } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to request the MAC table from the device. Switches currently support this feature. This endpoint has a sustained rate limit of one request every five seconds per device, with an allowed burst of five requests.", "operationId": "createDeviceLiveToolsMacTable", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } } } } }, "required": false }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "macTableId": { "type": "string", "description": "ID of the MAC table request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your MAC table request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "MAC table request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the MAC table request." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "macTableId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/macTable/1284392014819", "request": { "serial": "Q234-ABCD-5678" }, "status": "complete", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:write" ] } ], "summary": "Enqueue a job to request the MAC table from the device", "tags": [ "devices", "liveTools", "macTable" ] } }, "/devices/{serial}/liveTools/macTable/{macTableId}": { "get": { "description": "Return a MAC table live tool job.", "operationId": "getDeviceLiveToolsMacTable", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "macTableId", "in": "path", "description": "Mac table ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "macTableId": { "type": "string", "description": "ID of the MAC table request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your MAC table request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "MAC table request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the MAC table request." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "mac": { "type": "string", "description": "The MAC address of the MAC entry" }, "port": { "type": "string", "description": "The name of the interface of the MAC entry" }, "vlanId": { "type": "integer", "description": "The vlan id of the MAC entry" } } }, "description": "MAC address table entries" }, "error": { "type": "string", "description": "An error message for a failed execution" } } }, "example": { "macTableId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/macTable/1284392014819", "request": { "serial": "Q234-ABCD-5678" }, "status": "complete", "entries": [ { "mac": "00:11:22:a0:b1:c2", "port": "Tw1/0/9", "vlanId": 100 } ], "error": "The device is unreachable." } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:read" ] } ], "summary": "Return a MAC table live tool job.", "tags": [ "devices", "liveTools", "macTable" ] } }, "/devices/{serial}/liveTools/multicastRouting": { "post": { "callbacks": { "multicastRouting": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "multicastRoutingId": { "type": "string", "description": "ID of the Multicast routing request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this URL to check the status of your Multicast routing request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "Multicast routing request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the Multicast routing request." }, "interfaces": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string", "description": "Interface IP address" }, "name": { "type": "string", "description": "Interface name" }, "vrf": { "type": "string", "description": "VRF name for the interface. Included on networks with IOS XE 17.18 or higher" }, "vrfType": { "type": "string", "description": "VRF type for the interface. Included on networks with IOS XE 17.18 or higher" }, "ipVersion": { "type": "string", "description": "IP version for the interface. Included on networks with IOS XE 17.18 or higher" }, "subnet": { "type": "string", "description": "Subnet containing the interface" }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "DISABLED", "DOWN", "DR", "DVMRP", "NO-NBR", "PIM" ] }, "description": "List of flags (unordered)" }, "neighbors": { "type": "array", "items": { "type": "string" }, "description": "Array of PIM Neighbor IP Addresses" } } }, "description": "The interfaces that have PIM enabled" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "Source IP or \"Any\"" }, "group": { "type": "string", "description": "Group IP address" }, "vrf": { "type": "string", "description": "VRF name for the route. Included on networks with IOS XE 17.18 or higher" }, "ipVersion": { "type": "string", "description": "IP version for the route. Included on networks with IOS XE 17.18 or higher" }, "rendezvousPoint": { "type": "string", "description": "IP address of the rendezvous point" }, "incomingInterfaceName": { "type": "string", "description": "Name of the Virtual Interface traffic is arriving on" }, "outgoingInterfaceNames": { "type": "array", "items": { "type": "string" }, "description": "Array of outgoing Virtual Interface names" }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "ASSERTED", "CACHE", "IIF_REG", "NULL_OIF", "PMBR", "REG", "REG_SUPP", "RP", "SG", "SPT", "WC" ] }, "description": "List of flags (unordered)" } } }, "description": "The multicast routes" }, "error": { "type": "string", "description": "Description of the error." } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to perform a Multicast routing request for the device. This endpoint currently supports switches. This endpoint has a sustained rate limit of one request every five seconds per device, with an allowed burst of five requests.", "operationId": "createDeviceLiveToolsMulticastRouting", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } } } } }, "required": false }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "multicastRoutingId": { "type": "string", "description": "ID of the Multicast routing request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this URL to check the status of your Multicast routing request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "Multicast routing request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the Multicast routing request." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "multicastRoutingId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/multicastRouting/1284392014819", "request": { "serial": "Q234-ABCD-5678" }, "status": "complete", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:write" ] } ], "summary": "Enqueue a job to perform a Multicast routing request for the device", "tags": [ "devices", "liveTools", "multicastRouting" ] } }, "/devices/{serial}/liveTools/multicastRouting/{multicastRoutingId}": { "get": { "description": "Return a Multicast routing live tool job.", "operationId": "getDeviceLiveToolsMulticastRouting", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "multicastRoutingId", "in": "path", "description": "Multicast routing ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "multicastRoutingId": { "type": "string", "description": "ID of the Multicast routing request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this URL to check the status of your Multicast routing request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "Multicast routing request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the Multicast routing request." }, "interfaces": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string", "description": "Interface IP address" }, "name": { "type": "string", "description": "Interface name" }, "vrf": { "type": "string", "description": "VRF name for the interface. Included on networks with IOS XE 17.18 or higher" }, "vrfType": { "type": "string", "description": "VRF type for the interface. Included on networks with IOS XE 17.18 or higher" }, "ipVersion": { "type": "string", "description": "IP version for the interface. Included on networks with IOS XE 17.18 or higher" }, "subnet": { "type": "string", "description": "Subnet containing the interface" }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "DISABLED", "DOWN", "DR", "DVMRP", "NO-NBR", "PIM" ] }, "description": "List of flags (unordered)" }, "neighbors": { "type": "array", "items": { "type": "string" }, "description": "Array of PIM Neighbor IP Addresses" } } }, "description": "The interfaces that have PIM enabled" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "Source IP or \"Any\"" }, "group": { "type": "string", "description": "Group IP address" }, "vrf": { "type": "string", "description": "VRF name for the route. Included on networks with IOS XE 17.18 or higher" }, "ipVersion": { "type": "string", "description": "IP version for the route. Included on networks with IOS XE 17.18 or higher" }, "rendezvousPoint": { "type": "string", "description": "IP address of the rendezvous point" }, "incomingInterfaceName": { "type": "string", "description": "Name of the Virtual Interface traffic is arriving on" }, "outgoingInterfaceNames": { "type": "array", "items": { "type": "string" }, "description": "Array of outgoing Virtual Interface names" }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "ASSERTED", "CACHE", "IIF_REG", "NULL_OIF", "PMBR", "REG", "REG_SUPP", "RP", "SG", "SPT", "WC" ] }, "description": "List of flags (unordered)" } } }, "description": "The multicast routes" }, "error": { "type": "string", "description": "Description of the error." } } }, "example": { "multicastRoutingId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/multicastRouting/1284392014819", "request": { "serial": "Q234-ABCD-5678" }, "status": "complete", "interfaces": [ { "ip": "1.2.3.4", "name": "Vlan20", "vrf": "IPv4 default", "vrfType": "vrf", "ipVersion": "ipv4", "subnet": "192.168.1.0/24", "flags": [ "PIM" ], "neighbors": [ "123.123.123.1" ] } ], "routes": [ { "source": "1.2.3.4", "group": "1.2.3.5", "vrf": "IPv4 default", "ipVersion": "ipv4", "rendezvousPoint": "10.0.0.0/24", "incomingInterfaceName": "Vlan100", "outgoingInterfaceNames": [ "Vlan20", "Vlan50" ], "flags": [ "SPT" ] } ], "error": "The device is unreachable." } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:read" ] } ], "summary": "Return a Multicast routing live tool job.", "tags": [ "devices", "liveTools", "multicastRouting" ] } }, "/devices/{serial}/liveTools/ping": { "post": { "callbacks": { "pingHost": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "pingId": { "type": "string", "description": "Id to check the status of your ping request." }, "url": { "type": "string", "description": "GET this url to check the status of your ping request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "target": { "type": "string", "description": "IP address or FQDN to ping" }, "count": { "type": "integer", "description": "Number of pings to send. [1..5], default 5" } }, "description": "Ping request parameters" }, "status": { "type": "string", "description": "Status of the ping request." }, "results": { "type": "object", "properties": { "sent": { "type": "integer", "description": "Number of packets sent" }, "received": { "type": "integer", "description": "Number of packets received" }, "loss": { "type": "object", "properties": { "percentage": { "type": "number", "format": "float", "description": "Percentage of packets lost" } }, "description": "Lost packets" }, "latencies": { "type": "object", "properties": { "minimum": { "type": "number", "format": "float", "description": "Minimum latency" }, "average": { "type": "number", "format": "float", "description": "Average latency" }, "maximum": { "type": "number", "format": "float", "description": "Maximum latency" } }, "description": "Packet latency stats" }, "replies": { "type": "array", "items": { "type": "object", "properties": { "sequenceId": { "type": "integer", "description": "Sequence ID of the packet" }, "size": { "type": "integer", "description": "Size of the packet in bytes" }, "latency": { "type": "number", "format": "float", "description": "Latency of the packet in milliseconds" } } }, "description": "Received packets" } }, "description": "Results of the ping request." } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to ping a target host from the device. This endpoint has a sustained rate limit of one request every five seconds per device, with an allowed burst of five requests.", "operationId": "createDeviceLiveToolsPing", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "description": "FQDN, IPv4 or IPv6 address" }, "count": { "type": "integer", "description": "Count parameter to pass to ping. [1..5], default 5" }, "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "target": "75.75.75.75", "count": 2, "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } }, "required": [ "target" ] } } }, "required": true }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "pingId": { "type": "string", "description": "Id to check the status of your ping request." }, "url": { "type": "string", "description": "GET this url to check the status of your ping request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "target": { "type": "string", "description": "IP address or FQDN to ping" }, "count": { "type": "integer", "description": "Number of pings to send. [1..5], default 5" } }, "description": "Ping request parameters" }, "status": { "type": "string", "description": "Status of the ping request." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "pingId": "1284392014819", "url": "/devices/SERIAL/liveTools/ping/1284392014819", "request": { "serial": "Q234-ABCD-5678", "target": "75.75.75.75", "count": 2 }, "status": "complete", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:write" ] } ], "summary": "Enqueue a job to ping a target host from the device", "tags": [ "devices", "liveTools", "ping" ] } }, "/devices/{serial}/liveTools/ping/{id}": { "get": { "description": "Return a ping job. Latency unit in response is in milliseconds. Size is in bytes.", "operationId": "getDeviceLiveToolsPing", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "path", "description": "ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "pingId": { "type": "string", "description": "Id to check the status of your ping request." }, "url": { "type": "string", "description": "GET this url to check the status of your ping request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "target": { "type": "string", "description": "IP address or FQDN to ping" }, "count": { "type": "integer", "description": "Number of pings to send. [1..5], default 5" } }, "description": "Ping request parameters" }, "status": { "type": "string", "description": "Status of the ping request." }, "results": { "type": "object", "properties": { "sent": { "type": "integer", "description": "Number of packets sent" }, "received": { "type": "integer", "description": "Number of packets received" }, "loss": { "type": "object", "properties": { "percentage": { "type": "number", "format": "float", "description": "Percentage of packets lost" } }, "description": "Lost packets" }, "latencies": { "type": "object", "properties": { "minimum": { "type": "number", "format": "float", "description": "Minimum latency" }, "average": { "type": "number", "format": "float", "description": "Average latency" }, "maximum": { "type": "number", "format": "float", "description": "Maximum latency" } }, "description": "Packet latency stats" }, "replies": { "type": "array", "items": { "type": "object", "properties": { "sequenceId": { "type": "integer", "description": "Sequence ID of the packet" }, "size": { "type": "integer", "description": "Size of the packet in bytes" }, "latency": { "type": "number", "format": "float", "description": "Latency of the packet in milliseconds" } } }, "description": "Received packets" } }, "description": "Results of the ping request." } } }, "example": { "pingId": "1284392014819", "url": "/devices/SERIAL/liveTools/ping/1284392014819", "request": { "serial": "Q234-ABCD-5678", "target": "75.75.75.75", "count": 2 }, "status": "complete", "results": { "sent": 5, "received": 5, "loss": { "percentage": 0.0 }, "latencies": { "minimum": 15.8, "average": 15.8, "maximum": 15.9 }, "replies": [ { "sequenceId": 1, "size": 84, "latency": 15.7 } ] } } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:read" ] } ], "summary": "Return a ping job", "tags": [ "devices", "liveTools", "ping" ] } }, "/devices/{serial}/liveTools/pingDevice": { "post": { "callbacks": { "pingDevice": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "pingId": { "type": "string", "description": "Id to check the status of your ping request." }, "url": { "type": "string", "description": "GET this url to check the status of your ping request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "count": { "type": "integer", "description": "Number of pings to send. [1..5], default 5" } }, "description": "Ping request parameters" }, "status": { "type": "string", "description": "Status of the ping request." }, "results": { "type": "object", "properties": { "sent": { "type": "integer", "description": "Number of packets sent" }, "received": { "type": "integer", "description": "Number of packets received" }, "loss": { "type": "object", "properties": { "percentage": { "type": "number", "format": "float", "description": "Percentage of packets lost" } }, "description": "Lost packets" }, "latencies": { "type": "object", "properties": { "minimum": { "type": "number", "format": "float", "description": "Minimum latency" }, "average": { "type": "number", "format": "float", "description": "Average latency" }, "maximum": { "type": "number", "format": "float", "description": "Maximum latency" } }, "description": "Packet latency stats" }, "replies": { "type": "array", "items": { "type": "object", "properties": { "sequenceId": { "type": "integer", "description": "Sequence ID of the packet" }, "size": { "type": "integer", "description": "Size of the packet in bytes" }, "latency": { "type": "number", "format": "float", "description": "Latency of the packet in milliseconds" } } }, "description": "Received packets" } }, "description": "Results of the ping request." } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to check connectivity status to the device. This endpoint has a sustained rate limit of one request every five seconds per device, with an allowed burst of five requests.", "operationId": "createDeviceLiveToolsPingDevice", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Count parameter to pass to ping. [1..5], default 5" }, "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "count": 3, "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } } } } }, "required": false }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "pingId": { "type": "string", "description": "Id to check the status of your ping request." }, "url": { "type": "string", "description": "GET this url to check the status of your ping request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "count": { "type": "integer", "description": "Number of pings to send. [1..5], default 5" } }, "description": "Ping request parameters" }, "status": { "type": "string", "description": "Status of the ping request." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "pingId": "1284392014819", "url": "/devices/SERIAL/liveTools/pingDevice/1284392014819", "request": { "serial": "Q234-ABCD-5678", "count": 2 }, "status": "complete", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:write" ] } ], "summary": "Enqueue a job to check connectivity status to the device", "tags": [ "devices", "liveTools", "pingDevice" ] } }, "/devices/{serial}/liveTools/pingDevice/{id}": { "get": { "description": "Return a ping device job. Latency unit in response is in milliseconds. Size is in bytes.", "operationId": "getDeviceLiveToolsPingDevice", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "path", "description": "ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "pingId": { "type": "string", "description": "Id to check the status of your ping request." }, "url": { "type": "string", "description": "GET this url to check the status of your ping request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "count": { "type": "integer", "description": "Number of pings to send. [1..5], default 5" } }, "description": "Ping request parameters" }, "status": { "type": "string", "description": "Status of the ping request." }, "results": { "type": "object", "properties": { "sent": { "type": "integer", "description": "Number of packets sent" }, "received": { "type": "integer", "description": "Number of packets received" }, "loss": { "type": "object", "properties": { "percentage": { "type": "number", "format": "float", "description": "Percentage of packets lost" } }, "description": "Lost packets" }, "latencies": { "type": "object", "properties": { "minimum": { "type": "number", "format": "float", "description": "Minimum latency" }, "average": { "type": "number", "format": "float", "description": "Average latency" }, "maximum": { "type": "number", "format": "float", "description": "Maximum latency" } }, "description": "Packet latency stats" }, "replies": { "type": "array", "items": { "type": "object", "properties": { "sequenceId": { "type": "integer", "description": "Sequence ID of the packet" }, "size": { "type": "integer", "description": "Size of the packet in bytes" }, "latency": { "type": "number", "format": "float", "description": "Latency of the packet in milliseconds" } } }, "description": "Received packets" } }, "description": "Results of the ping request." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "pingId": "1284392014819", "url": "/devices/SERIAL/liveTools/pingDevice/1284392014819", "request": { "serial": "Q234-ABCD-5678", "count": 2 }, "status": "complete", "results": { "sent": 5, "received": 5, "loss": { "percentage": 0.0 }, "latencies": { "minimum": 15.8, "average": 15.8, "maximum": 15.9 }, "replies": [ { "sequenceId": 1, "size": 84, "latency": 15.7 } ] }, "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:read" ] } ], "summary": "Return a ping device job", "tags": [ "devices", "liveTools", "pingDevice" ] } }, "/devices/{serial}/liveTools/ports/cycle": { "post": { "callbacks": { "cyclePort": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "cyclePortId": { "type": "string", "description": "ID of the cycle port request" }, "url": { "type": "string", "description": "GET this URL to check the status of your cycle port request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "ports": { "type": "array", "items": { "type": "string" }, "description": "A list of ports to cycle" } }, "description": "Cycle port request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the cycle port request" }, "error": { "type": "string", "description": "An error message for a failed cycle port execution, if present" } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to perform a cycle port for the device on the specified ports. This endpoint has a sustained rate limit of one request every five seconds per device, with an allowed burst of five requests.", "operationId": "createDeviceLiveToolsPortsCycle", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ports": { "type": "array", "items": { "type": "string" }, "description": "A list of ports to cycle. For Catalyst switches, IOS interface names are also supported, such as \"GigabitEthernet1/0/8\", \"Gi1/0/8\", or even \"1/0/8\"." }, "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "ports": [ "2", "8" ], "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } }, "required": [ "ports" ] } } }, "required": true }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "cyclePortId": { "type": "string", "description": "ID of the cycle port request" }, "url": { "type": "string", "description": "GET this URL to check the status of your cycle port request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "ports": { "type": "array", "items": { "type": "string" }, "description": "A list of ports to cycle" } }, "description": "Cycle port request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the cycle port request" }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "cyclePortId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/ports/cycle/1284392014819", "request": { "serial": "Q234-ABCD-5678", "ports": [ "2", "8" ] }, "status": "complete", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:write" ] } ], "summary": "Enqueue a job to perform a cycle port for the device on the specified ports", "tags": [ "devices", "liveTools", "ports", "cycle" ] } }, "/devices/{serial}/liveTools/ports/cycle/{id}": { "get": { "description": "Return a cycle port live tool job.", "operationId": "getDeviceLiveToolsPortsCycle", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "path", "description": "ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "cyclePortId": { "type": "string", "description": "ID of the cycle port request" }, "url": { "type": "string", "description": "GET this URL to check the status of your cycle port request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "ports": { "type": "array", "items": { "type": "string" }, "description": "A list of ports to cycle" } }, "description": "Cycle port request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the cycle port request" }, "error": { "type": "string", "description": "An error message for a failed cycle port execution, if present" } } }, "example": { "cyclePortId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/ports/cycle/1284392014819", "request": { "serial": "Q234-ABCD-5678", "ports": [ "2", "8" ] }, "status": "complete", "error": "The device is unreachable." } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:read" ] } ], "summary": "Return a cycle port live tool job.", "tags": [ "devices", "liveTools", "ports", "cycle" ] } }, "/devices/{serial}/liveTools/ports/status": { "post": { "callbacks": { "portStatus": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Id of the port status request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your port status request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "Port status request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the port status request." }, "results": { "type": "array", "items": { "type": "object", "properties": { "portId": { "type": "integer", "description": "The identifier for the port" }, "interface": { "type": "object", "properties": { "name": { "type": "string", "description": "The full interface identifier for this port" }, "slot": { "type": "integer", "description": "The slot for this port" }, "subslot": { "type": "integer", "description": "The subslot for this port" }, "number": { "type": "integer", "description": "The leaf interface number for this port" } }, "description": "The structured interface identifier for this port" }, "speed": { "type": "string", "description": "The negotiated port speed" }, "status": { "type": "string", "enum": [ "connected", "disconnected" ], "description": "The current link status of the port" }, "duplex": { "type": "boolean", "description": "Whether the port is in full-duplex mode" }, "enabled": { "type": "boolean", "description": "Whether the port is administratively enabled" }, "power": { "type": "object", "properties": { "isDrawing": { "type": "boolean", "description": "Whether the port is drawing power" } }, "description": "Power state of the port" } } }, "description": "Port status results" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Any errors encountered while retrieving port status" } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to retrieve port status for a device. This endpoint has a sustained rate limit of one request every five seconds per device, with an allowed burst of five requests.", "operationId": "createDeviceLiveToolsPortsStatus", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } } } } }, "required": false }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Id of the port status request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your port status request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "Port status request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the port status request." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "jobId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/ports/status/1284392014819", "request": { "serial": "Q234-ABCD-5678" }, "status": "complete", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:write" ] } ], "summary": "Enqueue a job to retrieve port status for a device", "tags": [ "devices", "liveTools", "ports", "status" ] } }, "/devices/{serial}/liveTools/ports/status/{jobId}": { "get": { "description": "Return a port status live tool job.", "operationId": "getDeviceLiveToolsPortsStatus", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "jobId", "in": "path", "description": "Job ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Id of the port status request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your port status request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "Port status request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the port status request." }, "results": { "type": "array", "items": { "type": "object", "properties": { "portId": { "type": "integer", "description": "The identifier for the port" }, "interface": { "type": "object", "properties": { "name": { "type": "string", "description": "The full interface identifier for this port" }, "slot": { "type": "integer", "description": "The slot for this port" }, "subslot": { "type": "integer", "description": "The subslot for this port" }, "number": { "type": "integer", "description": "The leaf interface number for this port" } }, "description": "The structured interface identifier for this port" }, "speed": { "type": "string", "description": "The negotiated port speed" }, "status": { "type": "string", "enum": [ "connected", "disconnected" ], "description": "The current link status of the port" }, "duplex": { "type": "boolean", "description": "Whether the port is in full-duplex mode" }, "enabled": { "type": "boolean", "description": "Whether the port is administratively enabled" }, "power": { "type": "object", "properties": { "isDrawing": { "type": "boolean", "description": "Whether the port is drawing power" } }, "description": "Power state of the port" } } }, "description": "Port status results" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Any errors encountered while retrieving port status" } } }, "example": { "jobId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/ports/status/1284392014819", "request": { "serial": "Q234-ABCD-5678" }, "status": "complete", "results": [ { "portId": 0, "interface": { "name": "GigabitEthernet0/0/0", "slot": 0, "subslot": 0, "number": 0 }, "speed": "1 Gbps", "status": "connected", "duplex": true, "enabled": true, "power": { "isDrawing": false } } ], "errors": [ "The device is unreachable." ] } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:read" ] } ], "summary": "Return a port status live tool job.", "tags": [ "devices", "liveTools", "ports", "status" ] } }, "/devices/{serial}/liveTools/power/usage": { "post": { "callbacks": { "powerUsage": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Id of the power usage request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your power usage request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "Power usage request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the power usage request." }, "results": { "type": "object", "properties": { "instant": { "type": "number", "format": "float", "description": "Instantaneous device power usage measured when this job result was generated." }, "peak": { "type": "number", "format": "float", "description": "Highest device power usage observed since the last reboot." }, "budget": { "type": "number", "format": "float", "description": "Total power reserved for the device, defined by hardware and system specifications." } }, "description": "Power values, in watts, reported by the device for this job result." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Any errors encountered while retrieving power usage details" } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueues a live tool job that retrieves details about a device's overall power usage. This endpoint has a sustained rate limit of one request every five seconds per device, with an allowed burst of five requests.", "operationId": "createDeviceLiveToolsPowerUsage", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } } } } }, "required": false }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Id of the power usage request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your power usage request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "Power usage request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the power usage request." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "jobId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/power/usage/1284392014819", "request": { "serial": "Q234-ABCD-5678" }, "status": "complete", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:write" ] } ], "summary": "Enqueues a live tool job that retrieves details about a device's overall power usage", "tags": [ "devices", "liveTools", "power", "usage" ] } }, "/devices/{serial}/liveTools/power/usage/{jobId}": { "get": { "description": "Retrieve the status and results of a previously created live tool job fetching details about a device's overall power usage.", "operationId": "getDeviceLiveToolsPowerUsage", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "jobId", "in": "path", "description": "Job ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Id of the power usage request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your power usage request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "Power usage request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the power usage request." }, "results": { "type": "object", "properties": { "instant": { "type": "number", "format": "float", "description": "Instantaneous device power usage measured when this job result was generated." }, "peak": { "type": "number", "format": "float", "description": "Highest device power usage observed since the last reboot." }, "budget": { "type": "number", "format": "float", "description": "Total power reserved for the device, defined by hardware and system specifications." } }, "description": "Power values, in watts, reported by the device for this job result." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Any errors encountered while retrieving power usage details" } } }, "example": { "jobId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/power/usage/1284392014819", "request": { "serial": "Q234-ABCD-5678" }, "status": "complete", "results": { "instant": 32.0, "peak": 33.0, "budget": 25.0 }, "errors": [ "The device is unreachable." ] } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:read" ] } ], "summary": "Retrieve the status and results of a previously created live tool job fetching details about a device's overall power usage.", "tags": [ "devices", "liveTools", "power", "usage" ] } }, "/devices/{serial}/liveTools/routingTable/lookups": { "post": { "callbacks": { "routingTable": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "lookupId": { "type": "string", "description": "Id of the route table lookup request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your routing table lookup request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "type": { "type": "string", "enum": [ "BGP", "EIGRP", "HSRP", "IGRP", "ISIS", "LISP", "NAT", "ND", "NHRP", "OMP", "OSPF", "RIP", "default WAN", "direct", "static" ], "description": "The type of route defined" }, "destination": { "type": "object", "properties": { "address": { "type": "string", "description": "The destination IP address to find a longest prefix match route" }, "subnet": { "type": "string", "description": "The destination subnet in CIDR format to find matching routes" } }, "description": "The destination details to lookup" }, "nextHop": { "type": "object", "properties": { "address": { "type": "string", "description": "The IP address of the next hop" } }, "description": "The next hop to lookup" }, "vpn": { "type": "object", "properties": { "peer": { "type": "object", "properties": { "id": { "type": "string", "description": "The Network ID of the VPN peer" } }, "description": "The VPN peer to lookup" } }, "description": "VPN related search criteria" } }, "description": "Routing table lookup request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the routing table lookup request." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BGP", "EIGRP", "HSRP", "IGRP", "ISIS", "LISP", "NAT", "ND", "NHRP", "OMP", "OSPF", "RIP", "default WAN", "direct", "static" ], "description": "The type of route defined" }, "subnet": { "type": "string", "description": "The subnet of the route in CIDR format" }, "nextHops": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer", "description": "The priority of the next hop starting from 0. Lower numbers indicate higher priority." }, "address": { "type": "string", "description": "The IP address of the next hop" }, "vpn": { "type": "object", "properties": { "peer": { "type": "object", "properties": { "id": { "type": "string", "description": "The Network ID of the VPN peer" }, "name": { "type": "string", "description": "The name of the VPN peer" } }, "description": "The VPN peer details" } }, "description": "The VPN peer details, if the next hop is a VPN peer" } } }, "description": "Ordered list of ECMP(Equal cost multiple path) next hops for the destination subnet" }, "ipVersion": { "type": "string", "enum": [ "ipv4", "ipv6" ], "description": "The IP version of the route'" }, "vrf": { "type": "object", "properties": { "name": { "type": "string", "description": "VRF name" } }, "description": "The VRF details for the route" } } }, "description": "Routing table entries that match the search criteria" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "An error message for a failed execution" } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to perform a routing table lookup request for a device. The routing table lookup request fetches a specific set of routes based on filters. Any combination of search filters can be applied. Only Cisco Secure Routers are supported.", "operationId": "createDeviceLiveToolsRoutingTableLookup", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BGP", "EIGRP", "HSRP", "IGRP", "ISIS", "LISP", "NAT", "ND", "NHRP", "OMP", "OSPF", "RIP", "default WAN", "direct", "static" ], "description": "The type of route defined" }, "destination": { "type": "object", "properties": { "address": { "type": "string", "description": "The destination IP address to find a longest prefix match route" }, "subnet": { "type": "string", "description": "The destination subnet in CIDR format to find matching routes" } }, "description": "The destination IP or subnet to lookup" }, "nextHop": { "type": "object", "properties": { "address": { "type": "string", "description": "The IP address of the next hop" } }, "description": "The next hop to lookup" }, "vpn": { "type": "object", "properties": { "peer": { "type": "object", "properties": { "id": { "type": "string", "description": "The Network ID of the VPN peer" } }, "description": "The VPN peer to lookup" } }, "description": "VPN related search criteria" }, "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "type": "static", "destination": { "address": "192.168.0.10", "subnet": "192.168.0.0/24" }, "nextHop": { "address": "10.10.0.1" }, "vpn": { "peer": { "id": "N_12345678" } }, "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } } } } }, "required": false }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "lookupId": { "type": "string", "description": "Id of the route table lookup request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your routing table lookup request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "type": { "type": "string", "enum": [ "BGP", "EIGRP", "HSRP", "IGRP", "ISIS", "LISP", "NAT", "ND", "NHRP", "OMP", "OSPF", "RIP", "default WAN", "direct", "static" ], "description": "The type of route defined" }, "destination": { "type": "object", "properties": { "address": { "type": "string", "description": "The destination IP address to find a longest prefix match route" }, "subnet": { "type": "string", "description": "The destination subnet in CIDR format to find matching routes" } }, "description": "The destination details to lookup" }, "nextHop": { "type": "object", "properties": { "address": { "type": "string", "description": "The IP address of the next hop" } }, "description": "The next hop to lookup" }, "vpn": { "type": "object", "properties": { "peer": { "type": "object", "properties": { "id": { "type": "string", "description": "The Network ID of the VPN peer" } }, "description": "The VPN peer to lookup" } }, "description": "VPN related search criteria" } }, "description": "Routing table lookup request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the routing table lookup request." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "lookupId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/routingTable/lookups/1284392014819", "request": { "serial": "Q234-ABCD-5678", "type": "static", "destination": { "address": "192.168.0.10", "subnet": "192.168.0.0/24" }, "nextHop": { "address": "10.10.0.1" }, "vpn": { "peer": { "id": "N_12345678" } } }, "status": "scheduled", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "sdwan:telemetry:write" ] } ], "summary": "Enqueue a job to perform a routing table lookup request for a device", "tags": [ "devices", "liveTools", "routingTable", "lookups" ] } }, "/devices/{serial}/liveTools/routingTable/lookups/{id}": { "get": { "description": "Return a routing table live tool lookup job for a device. The response contains the details of the job, including the filters used for the routing table lookup request and the results of the request if the job has completed. Only Cisco Secure Routers are supported.", "operationId": "getDeviceLiveToolsRoutingTableLookup", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "path", "description": "ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "lookupId": { "type": "string", "description": "Id of the route table lookup request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your routing table lookup request." }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "type": { "type": "string", "enum": [ "BGP", "EIGRP", "HSRP", "IGRP", "ISIS", "LISP", "NAT", "ND", "NHRP", "OMP", "OSPF", "RIP", "default WAN", "direct", "static" ], "description": "The type of route defined" }, "destination": { "type": "object", "properties": { "address": { "type": "string", "description": "The destination IP address to find a longest prefix match route" }, "subnet": { "type": "string", "description": "The destination subnet in CIDR format to find matching routes" } }, "description": "The destination details to lookup" }, "nextHop": { "type": "object", "properties": { "address": { "type": "string", "description": "The IP address of the next hop" } }, "description": "The next hop to lookup" }, "vpn": { "type": "object", "properties": { "peer": { "type": "object", "properties": { "id": { "type": "string", "description": "The Network ID of the VPN peer" } }, "description": "The VPN peer to lookup" } }, "description": "VPN related search criteria" } }, "description": "Routing table lookup request parameters" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the routing table lookup request." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BGP", "EIGRP", "HSRP", "IGRP", "ISIS", "LISP", "NAT", "ND", "NHRP", "OMP", "OSPF", "RIP", "default WAN", "direct", "static" ], "description": "The type of route defined" }, "subnet": { "type": "string", "description": "The subnet of the route in CIDR format" }, "nextHops": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer", "description": "The priority of the next hop starting from 0. Lower numbers indicate higher priority." }, "address": { "type": "string", "description": "The IP address of the next hop" }, "vpn": { "type": "object", "properties": { "peer": { "type": "object", "properties": { "id": { "type": "string", "description": "The Network ID of the VPN peer" }, "name": { "type": "string", "description": "The name of the VPN peer" } }, "description": "The VPN peer details" } }, "description": "The VPN peer details, if the next hop is a VPN peer" } } }, "description": "Ordered list of ECMP(Equal cost multiple path) next hops for the destination subnet" }, "ipVersion": { "type": "string", "enum": [ "ipv4", "ipv6" ], "description": "The IP version of the route'" }, "vrf": { "type": "object", "properties": { "name": { "type": "string", "description": "VRF name" } }, "description": "The VRF details for the route" } } }, "description": "Routing table entries that match the search criteria" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "An error message for a failed execution" } } }, "example": { "lookupId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/routingTable/lookups/1284392014819", "request": { "serial": "Q234-ABCD-5678", "type": "static", "destination": { "address": "192.168.0.10", "subnet": "192.168.0.0/24" }, "nextHop": { "address": "10.10.0.1" }, "vpn": { "peer": { "id": "N_12345678" } } }, "status": "scheduled", "entries": [ { "type": "static", "subnet": "192.168.0.0/24", "nextHops": [ { "number": 1, "address": "10.10.0.1", "vpn": { "peer": { "id": "N_12345678", "name": "Branch Office" } } } ], "ipVersion": "ipv4", "vrf": { "name": "default" } } ], "errors": [ "The device is unreachable" ] } } } } }, "security": [ { "oauth2": [ "sdwan:telemetry:read" ] } ], "summary": "Return a routing table live tool lookup job for a device", "tags": [ "devices", "liveTools", "routingTable", "lookups" ] } }, "/devices/{serial}/liveTools/routingTable/summaries": { "post": { "callbacks": { "routingTable": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "summaryId": { "type": "string", "description": "Id of the route table summary request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your routing table summary request." }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the routing table summary request." }, "counts": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of routes in the routing table" }, "byVrf": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the VRF" }, "byProtocol": { "type": "object", "properties": { "ipv4": { "type": "object", "properties": { "total": { "type": "integer", "description": "The total IPv4 route count in the VRF" } }, "description": "The IPv4 counts in the VRF" }, "ipv6": { "type": "object", "properties": { "total": { "type": "integer", "description": "The total IPv6 route count in the VRF" } }, "description": "The IPv6 counts in the VRF" } }, "description": "Routing table counts by protocol" } } }, "description": "Routing table counts by VRF" } }, "description": "Routing table summary counts" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "An error message for a failed execution" } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a routing table summary job for a device. The job fetches summary data such as route counts by VRF and protocol. Only Cisco Secure Routers are supported.", "operationId": "createDeviceLiveToolsRoutingTableSummary", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } } } } }, "required": false }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "summaryId": { "type": "string", "description": "Id of the route table summary request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your routing table summary request." }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the routing table summary request." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "summaryId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/routingTable/summaries/1284392014819", "status": "scheduled", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "sdwan:telemetry:write" ] } ], "summary": "Enqueue a routing table summary job for a device", "tags": [ "devices", "liveTools", "routingTable", "summaries" ] } }, "/devices/{serial}/liveTools/routingTable/summaries/{id}": { "get": { "description": "Return the status and result of a routing table summary job. The result consists of summary data such as route counts by VRF and protocol. Only Cisco Secure Routers are supported.", "operationId": "getDeviceLiveToolsRoutingTableSummary", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "id", "in": "path", "description": "ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "summaryId": { "type": "string", "description": "Id of the route table summary request. Used to check the status of the request." }, "url": { "type": "string", "description": "GET this url to check the status of your routing table summary request." }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the routing table summary request." }, "counts": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of routes in the routing table" }, "byVrf": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the VRF" }, "byProtocol": { "type": "object", "properties": { "ipv4": { "type": "object", "properties": { "total": { "type": "integer", "description": "The total IPv4 route count in the VRF" } }, "description": "The IPv4 counts in the VRF" }, "ipv6": { "type": "object", "properties": { "total": { "type": "integer", "description": "The total IPv6 route count in the VRF" } }, "description": "The IPv6 counts in the VRF" } }, "description": "Routing table counts by protocol" } } }, "description": "Routing table counts by VRF" } }, "description": "Routing table summary counts" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "An error message for a failed execution" } } }, "example": { "summaryId": "1284392014819", "url": "/devices/Q234-ABCD-5678/liveTools/routingTable/summaries/1284392014819", "status": "scheduled", "counts": { "total": 150, "byVrf": [ { "name": "default", "byProtocol": { "ipv4": { "total": 100 }, "ipv6": { "total": 50 } } } ] }, "errors": [ "The device is unreachable" ] } } } } }, "security": [ { "oauth2": [ "sdwan:telemetry:read" ] } ], "summary": "Return the status and result of a routing table summary job", "tags": [ "devices", "liveTools", "routingTable", "summaries" ] } }, "/devices/{serial}/liveTools/throughputTest": { "post": { "callbacks": { "throughputTest": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "throughputTestId": { "type": "string", "description": "ID of throughput test job" }, "url": { "type": "string", "description": "GET this url to check the status of your throughput test request" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the throughput test request" }, "result": { "type": "object", "properties": { "speeds": { "type": "object", "properties": { "downstream": { "type": "number", "format": "float", "description": "Shows the download speed from shard (Mbps)" } }, "description": "Shows the speeds (Mbps)" } }, "description": "Result of the throughput test request" }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "The parameters of the throughput test request" }, "error": { "type": "string", "description": "Description of the error." } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to test a device throughput, the test will run for 10 secs to test throughput. This endpoint has a rate limit of one request every five seconds per device.", "operationId": "createDeviceLiveToolsThroughputTest", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } } } } }, "required": false }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "throughputTestId": { "type": "string", "description": "ID of throughput test job" }, "url": { "type": "string", "description": "GET this url to check the status of your throughput test request" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the throughput test request" }, "result": { "type": "object", "properties": { "speeds": { "type": "object", "properties": { "downstream": { "type": "number", "format": "float", "description": "Shows the download speed from shard (Mbps)" } }, "description": "Shows the speeds (Mbps)" } }, "description": "Result of the throughput test request" }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "The parameters of the throughput test request" }, "error": { "type": "string", "description": "Description of the error." }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "throughputTestId": "123", "url": "/devices/QXXX-YYYY-ZZZZ/liveTools/throughputTest/123", "status": "complete", "result": { "speeds": { "downstream": 123.456789 } }, "request": { "serial": "Q234-ABCD-5678" }, "error": "error description", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:write" ] } ], "summary": "Enqueue a job to test a device throughput, the test will run for 10 secs to test throughput", "tags": [ "devices", "liveTools", "throughputTest" ] } }, "/devices/{serial}/liveTools/throughputTest/{throughputTestId}": { "get": { "description": "Return a throughput test job", "operationId": "getDeviceLiveToolsThroughputTest", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "throughputTestId", "in": "path", "description": "Throughput test ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "throughputTestId": { "type": "string", "description": "ID of throughput test job" }, "url": { "type": "string", "description": "GET this url to check the status of your throughput test request" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the throughput test request" }, "result": { "type": "object", "properties": { "speeds": { "type": "object", "properties": { "downstream": { "type": "number", "format": "float", "description": "Shows the download speed from shard (Mbps)" } }, "description": "Shows the speeds (Mbps)" } }, "description": "Result of the throughput test request" }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" } }, "description": "The parameters of the throughput test request" }, "error": { "type": "string", "description": "Description of the error." } } }, "example": { "throughputTestId": "123", "url": "/devices/QXXX-YYYY-ZZZZ/liveTools/throughputTest/123", "status": "complete", "result": { "speeds": { "downstream": 123.456789 } }, "request": { "serial": "Q234-ABCD-5678" }, "error": "error description" } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:read" ] } ], "summary": "Return a throughput test job", "tags": [ "devices", "liveTools", "throughputTest" ] } }, "/devices/{serial}/liveTools/wakeOnLan": { "post": { "callbacks": { "wakeOnLan": { "{$request.body#/callback/url}": { "post": { "requestBody": { "required": true, "description": "Callback payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "network": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "sentAt": { "type": "string" }, "callbackId": { "type": "string" }, "message": { "type": "object", "properties": { "wakeOnLanId": { "type": "string", "description": "ID of the Wake-on-LAN job" }, "url": { "type": "string", "description": "GET this url to check the status of your ping request" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the Wake-on-LAN request" }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "vlanId": { "type": "integer", "description": "The target's VLAN (1 to 4094)" }, "mac": { "type": "string", "description": "The target's MAC address" } }, "description": "The parameters of the Wake-on-LAN request" }, "error": { "type": "string", "description": "An error message for a failed execution" } } } } } } } }, "responses": { "2XX": { "description": "Your server return this code if it accepts the callback" } } } } } }, "description": "Enqueue a job to send a Wake-on-LAN packet from the device. This endpoint has a sustained rate limit of one request every five seconds per device, with an allowed burst of five requests.", "operationId": "createDeviceLiveToolsWakeOnLan", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "vlanId": { "type": "integer", "description": "The target's VLAN (1 to 4094)" }, "mac": { "type": "string", "description": "The target's MAC address" }, "callback": { "type": "object", "properties": { "url": { "type": "string", "description": "The callback URL for the webhook target. If using this field, please also specify a sharedSecret." }, "sharedSecret": { "type": "string", "description": "A shared secret that will be included in the requests sent to the callback URL. It can be used to verify that the request was sent by Meraki. If using this field, please also specify an url." }, "httpServer": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook receiver ID that will receive information. If specifying this, please leave the url and sharedSecret fields blank." } }, "description": "The webhook receiver used for the callback webhook." }, "payloadTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payload template. Defaults to 'wpt_00005' for the Callback (included) template." } }, "description": "The payload template of the webhook used for the callback" } }, "x-release-stage": "general_availability", "description": "Details for the callback. Please include either an httpServerId OR url and sharedSecret" } }, "example": { "vlanId": 12, "mac": "00:11:22:33:44:55", "callback": { "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "sharedSecret": "secret", "httpServer": { "id": "aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vd2ViaG9va3M=" }, "payloadTemplate": { "id": "wpt_2100" } } }, "required": [ "vlanId", "mac" ] } } }, "required": true }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "wakeOnLanId": { "type": "string", "description": "ID of the Wake-on-LAN job" }, "url": { "type": "string", "description": "GET this url to check the status of your ping request" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the Wake-on-LAN request" }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "vlanId": { "type": "integer", "description": "The target's VLAN (1 to 4094)" }, "mac": { "type": "string", "description": "The target's MAC address" } }, "description": "The parameters of the Wake-on-LAN request" }, "error": { "type": "string", "description": "An error message for a failed execution" }, "callback": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the callback. To check the status of the callback, use this ID in a request to /webhooks/callbacks/statuses/{id}" }, "url": { "type": "string", "description": "The callback URL for the webhook target. This was either provided in the original request or comes from a configured webhook receiver" }, "status": { "type": "string", "description": "The status of the callback" } }, "description": "Information for callback used to send back results", "x-release-stage": "general_availability" } } }, "example": { "wakeOnLanId": "123", "url": "/devices/QXXX-YYYY-ZZZZ/liveTools/wakeOnLan/1738", "status": "complete", "request": { "serial": "Q234-ABCD-5678", "vlanId": 12, "mac": "00:11:22:33:44:55" }, "error": "The device is unreachable.", "callback": { "id": "1284392014819", "url": "https://webhook.site/28efa24e-f830-4d9f-a12b-fbb9e5035031", "status": "new" } } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:write" ] } ], "summary": "Enqueue a job to send a Wake-on-LAN packet from the device", "tags": [ "devices", "liveTools", "wakeOnLan" ] } }, "/devices/{serial}/liveTools/wakeOnLan/{wakeOnLanId}": { "get": { "description": "Return a Wake-on-LAN job", "operationId": "getDeviceLiveToolsWakeOnLan", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "wakeOnLanId", "in": "path", "description": "Wake on lan ID", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "wakeOnLanId": { "type": "string", "description": "ID of the Wake-on-LAN job" }, "url": { "type": "string", "description": "GET this url to check the status of your ping request" }, "status": { "type": "string", "enum": [ "complete", "failed", "new", "ready", "running", "scheduled" ], "description": "Status of the Wake-on-LAN request" }, "request": { "type": "object", "properties": { "serial": { "type": "string", "description": "Device serial number" }, "vlanId": { "type": "integer", "description": "The target's VLAN (1 to 4094)" }, "mac": { "type": "string", "description": "The target's MAC address" } }, "description": "The parameters of the Wake-on-LAN request" }, "error": { "type": "string", "description": "An error message for a failed execution" } } }, "example": { "wakeOnLanId": "123", "url": "/devices/QXXX-YYYY-ZZZZ/liveTools/wakeOnLan/1738", "status": "complete", "request": { "serial": "Q234-ABCD-5678", "vlanId": 12, "mac": "00:11:22:33:44:55" }, "error": "The device is unreachable." } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:read" ] } ], "summary": "Return a Wake-on-LAN job", "tags": [ "devices", "liveTools", "wakeOnLan" ] } }, "/devices/{serial}/lldpCdp": { "get": { "description": "List LLDP and CDP information for a device", "operationId": "getDeviceLldpCdp", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceMac": { "type": "string", "description": "Source MAC address" }, "ports": { "type": "object", "additionalProperties": { "type": "object", "properties": { "lldp": { "type": "object", "properties": { "systemName": { "type": "string", "description": "Device system name" }, "systemDescription": { "type": "string", "description": "Device system description" }, "portId": { "type": "string", "description": "ID for the port" }, "chassisId": { "type": "string", "description": "Chassis ID" }, "managementVlan": { "type": "integer", "description": "Management VLAN" }, "portVlan": { "type": "integer", "description": "Port VLAN" }, "managementAddress": { "type": "string", "description": "Management IP address" }, "portDescription": { "type": "string", "description": "Port description" }, "systemCapabilities": { "type": "string", "description": "System capabilities" }, "sourcePort": { "type": "string", "description": "Source port" } }, "description": "lldp information" }, "cdp": { "type": "object", "properties": { "platform": { "type": "string", "description": "Platform" }, "deviceId": { "type": "string", "description": "ID for the device" }, "model": { "type": "string", "description": "Model for the device" }, "version": { "type": "string", "description": "Version for the device" }, "portId": { "type": "string", "description": "ID for the port" }, "nativeVlan": { "type": "integer", "description": "Native VLAN" }, "vtpManagementDomain": { "type": "string", "description": "VTP management domain" }, "capabilities": { "type": "string", "description": "Capabilities" }, "address": { "type": "string", "description": "Management IP address" }, "sourcePort": { "type": "string", "description": "Source port" } }, "description": "cdp information" }, "deviceMac": { "type": "string", "description": "MAC address for the device" }, "device": { "type": "object", "properties": { "url": { "type": "string", "description": "Dashboard Url for the device" } }, "description": "Associated device information" } }, "description": "lldp and/or cdp information, keyed by port" }, "description": "Mapping of ports to lldp and/or cdp information" } } }, "example": { "sourceMac": "00:11:22:33:44:55", "ports": { "22": { "lldp": { "systemName": "Meraki MS350-24X - Phineas", "systemDescription": "Meraki MX64 Cloud Managed Router", "portId": "11", "chassisId": "88:15:44:c8:5d:58", "managementVlan": 60, "portVlan": 500, "managementAddress": "192.168.1.128", "portDescription": "12", "systemCapabilities": "S-VLAN Component of a VLAN Bridge", "sourcePort": "12" }, "cdp": { "platform": "MS350-24X", "deviceId": "e0553d8cdf53", "model": "cisco C9300-24P", "version": "Catalyst L3 Switch Software (CAT9K_IOSXE), Experimental Version 17.6.20210422:140402", "portId": "Port 10", "nativeVlan": 1, "vtpManagementDomain": "cisco", "capabilities": "Switch", "address": "192.168.1.128", "sourcePort": "9" }, "deviceMac": "00:11:22:33:44:55", "device": { "url": "https://dashboard.meraki.com/Wireless-Testing/n/scPLfd/manage/nodes/new_list/194114551275232" } } } } } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:read" ] } ], "summary": "List LLDP and CDP information for a device", "tags": [ "devices", "monitor", "lldpCdp" ] } }, "/devices/{serial}/lossAndLatencyHistory": { "get": { "description": "Get the uplink loss percentage and latency in milliseconds, and goodput in kilobits per second for MX, MG and Z devices.", "operationId": "getDeviceLossAndLatencyHistory", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true }, { "name": "t0", "in": "query", "description": "The beginning of the timespan for the data. The maximum lookback period is 60 days from today.", "schema": { "type": "string" } }, { "name": "t1", "in": "query", "description": "The end of the timespan for the data. t1 can be a maximum of 31 days after t0.", "schema": { "type": "string" } }, { "name": "timespan", "in": "query", "description": "The timespan for which the information will be fetched. If specifying timespan, do not specify parameters t0 and t1. The value must be in seconds and be less than or equal to 31 days. The default is 1 day.", "schema": { "type": "number", "format": "float", "maximum": 2678400 } }, { "name": "resolution", "in": "query", "description": "The time resolution in seconds for returned data. The valid resolutions are: 60, 600, 3600, 86400. The default is 60.", "schema": { "type": "integer" } }, { "name": "uplink", "in": "query", "description": "The WAN uplink used to obtain the requested stats. Valid uplinks are wan1, wan2, wan3, cellular, wan4. The default is wan1.", "schema": { "type": "string", "enum": [ "cellular", "wan1", "wan2", "wan3", "wan4" ] } }, { "name": "ip", "in": "query", "required": true, "description": "The destination IP used to obtain the requested stats. This is required.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "startTime": { "type": "string", "format": "date-time", "description": "Start time of the sample" }, "endTime": { "type": "string", "format": "date-time", "description": "End time of the sample" }, "lossPercent": { "type": "number", "format": "float", "description": "Percentage of packets lost" }, "latencyMs": { "type": "number", "format": "float", "description": "Latency in milliseconds" }, "goodput": { "type": "integer", "description": "Number of useful information bits delivered" }, "jitter": { "type": "number", "format": "float", "description": "Jitter, in milliseconds" } } } }, "example": [ { "startTime": "2018-10-09T22:18:27Z", "endTime": "2018-10-09T22:19:27Z", "lossPercent": 5.23, "latencyMs": 324.12, "goodput": 1493, "jitter": 11.2 } ] } } } }, "security": [ { "oauth2": [ "dashboard:general:telemetry:read" ] } ], "summary": "Get the uplink loss percentage and latency in milliseconds, and goodput in kilobits per second for MX, MG and Z devices.", "tags": [ "devices", "monitor", "uplinks", "lossAndLatencyHistory" ] } }, "/devices/{serial}/managementInterface": { "get": { "description": "Return the management interface settings for a device", "operationId": "getDeviceManagementInterface", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ddnsHostnames": { "type": "object", "properties": { "activeDdnsHostname": { "type": "string", "description": "Active dynamic DNS hostname." }, "ddnsHostnameWan1": { "type": "string", "description": "WAN 1 dynamic DNS hostname." }, "ddnsHostnameWan2": { "type": "string", "description": "WAN 2 dynamic DNS hostname." } }, "description": "Dynamic DNS hostnames." }, "wan1": { "type": "object", "properties": { "wanEnabled": { "type": "string", "description": "Enable or disable the interface (only for MX devices). Valid values are 'enabled', 'disabled', and 'not configured'." }, "usingStaticIp": { "type": "boolean", "description": "Configure the interface to have static IP settings or use DHCP." }, "staticIp": { "type": "string", "description": "The IP the device should use on the WAN." }, "staticSubnetMask": { "type": "string", "description": "The subnet mask for the WAN." }, "staticGatewayIp": { "type": "string", "description": "The IP of the gateway on the WAN." }, "staticDns": { "type": "array", "items": { "type": "string" }, "description": "Up to two DNS IPs." }, "vlan": { "type": "integer", "description": "The VLAN that management traffic should be tagged with. Applies whether usingStaticIp is true or false." }, "vrf": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the VRF.", "nullable": true } }, "description": "VRF associated with the management interface. If not provided, the default VRF is used.", "nullable": true } }, "description": "WAN 1 settings" }, "wan2": { "type": "object", "properties": { "wanEnabled": { "type": "string", "description": "Enable or disable the interface (only for MX devices). Valid values are 'enabled', 'disabled', and 'not configured'." }, "usingStaticIp": { "type": "boolean", "description": "Configure the interface to have static IP settings or use DHCP." }, "staticIp": { "type": "string", "description": "The IP the device should use on the WAN." }, "staticSubnetMask": { "type": "string", "description": "The subnet mask for the WAN." }, "staticGatewayIp": { "type": "string", "description": "The IP of the gateway on the WAN." }, "staticDns": { "type": "array", "items": { "type": "string" }, "description": "Up to two DNS IPs." }, "vlan": { "type": "integer", "description": "The VLAN that management traffic should be tagged with. Applies whether usingStaticIp is true or false." }, "vrf": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the VRF.", "nullable": true } }, "description": "VRF associated with the management interface. If not provided, the default VRF is used.", "nullable": true } }, "description": "WAN 2 settings (only for MX devices)" } } }, "example": { "ddnsHostnames": { "activeDdnsHostname": "mx1-sample.dynamic-m.com", "ddnsHostnameWan1": "mx1-sample-1.dynamic-m.com", "ddnsHostnameWan2": "mx1-sample-2.dynamic-m.com" }, "wan1": { "wanEnabled": "not configured", "usingStaticIp": true, "staticIp": "1.2.3.4", "staticSubnetMask": "255.255.255.0", "staticGatewayIp": "1.2.3.1", "staticDns": [ "1.2.3.2", "1.2.3.3" ], "vlan": 7, "vrf": { "name": "Mgmt-vrf" } }, "wan2": { "wanEnabled": "enabled", "usingStaticIp": false, "staticIp": "1.2.3.4", "staticSubnetMask": "255.255.255.0", "staticGatewayIp": "1.2.3.1", "staticDns": [ "1.2.3.2", "1.2.3.3" ], "vlan": 2, "vrf": { "name": "Mgmt-vrf" } } } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:read" ] } ], "summary": "Return the management interface settings for a device", "tags": [ "devices", "configure", "managementInterface" ] }, "put": { "description": "Update the management interface settings for a device", "operationId": "updateDeviceManagementInterface", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "wan1": { "type": "object", "properties": { "wanEnabled": { "type": "string", "enum": [ "disabled", "enabled", "not configured" ], "description": "Enable or disable the interface (only for MX devices). Valid values are 'enabled', 'disabled', and 'not configured'." }, "usingStaticIp": { "type": "boolean", "description": "Configure the interface to have static IP settings or use DHCP." }, "staticIp": { "type": "string", "description": "The IP the device should use on the WAN." }, "staticGatewayIp": { "type": "string", "description": "The IP of the gateway on the WAN." }, "staticSubnetMask": { "type": "string", "description": "The subnet mask for the WAN." }, "staticDns": { "type": "array", "items": { "type": "string" }, "description": "Up to two DNS IPs." }, "vlan": { "type": "integer", "description": "The VLAN that management traffic should be tagged with. Applies whether usingStaticIp is true or false.", "nullable": true } }, "description": "WAN 1 settings" }, "wan2": { "type": "object", "properties": { "wanEnabled": { "type": "string", "enum": [ "disabled", "enabled", "not configured" ], "description": "Enable or disable the interface (only for MX devices). Valid values are 'enabled', 'disabled', and 'not configured'." }, "usingStaticIp": { "type": "boolean", "description": "Configure the interface to have static IP settings or use DHCP." }, "staticIp": { "type": "string", "description": "The IP the device should use on the WAN." }, "staticGatewayIp": { "type": "string", "description": "The IP of the gateway on the WAN." }, "staticSubnetMask": { "type": "string", "description": "The subnet mask for the WAN." }, "staticDns": { "type": "array", "items": { "type": "string" }, "description": "Up to two DNS IPs." }, "vlan": { "type": "integer", "description": "The VLAN that management traffic should be tagged with. Applies whether usingStaticIp is true or false.", "nullable": true } }, "description": "WAN 2 settings (only for MX devices)" } }, "example": { "wan1": { "wanEnabled": "not configured", "usingStaticIp": true, "staticIp": "1.2.3.4", "staticGatewayIp": "1.2.3.1", "staticSubnetMask": "255.255.255.0", "staticDns": [ "1.2.3.2", "1.2.3.3" ], "vlan": 7 }, "wan2": { "wanEnabled": "enabled", "usingStaticIp": false, "staticIp": "1.2.3.4", "staticGatewayIp": "1.2.3.1", "staticSubnetMask": "255.255.255.0", "staticDns": [ "1.2.3.2", "1.2.3.3" ], "vlan": 2 } } } } }, "required": false }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ddnsHostnames": { "type": "object", "properties": { "activeDdnsHostname": { "type": "string", "description": "Active dynamic DNS hostname." }, "ddnsHostnameWan1": { "type": "string", "description": "WAN 1 dynamic DNS hostname." }, "ddnsHostnameWan2": { "type": "string", "description": "WAN 2 dynamic DNS hostname." } }, "description": "Dynamic DNS hostnames." }, "wan1": { "type": "object", "properties": { "wanEnabled": { "type": "string", "description": "Enable or disable the interface (only for MX devices). Valid values are 'enabled', 'disabled', and 'not configured'." }, "usingStaticIp": { "type": "boolean", "description": "Configure the interface to have static IP settings or use DHCP." }, "staticIp": { "type": "string", "description": "The IP the device should use on the WAN." }, "staticSubnetMask": { "type": "string", "description": "The subnet mask for the WAN." }, "staticGatewayIp": { "type": "string", "description": "The IP of the gateway on the WAN." }, "staticDns": { "type": "array", "items": { "type": "string" }, "description": "Up to two DNS IPs." }, "vlan": { "type": "integer", "description": "The VLAN that management traffic should be tagged with. Applies whether usingStaticIp is true or false." }, "vrf": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the VRF.", "nullable": true } }, "description": "VRF associated with the management interface. If not provided, the default VRF is used.", "nullable": true } }, "description": "WAN 1 settings" }, "wan2": { "type": "object", "properties": { "wanEnabled": { "type": "string", "description": "Enable or disable the interface (only for MX devices). Valid values are 'enabled', 'disabled', and 'not configured'." }, "usingStaticIp": { "type": "boolean", "description": "Configure the interface to have static IP settings or use DHCP." }, "staticIp": { "type": "string", "description": "The IP the device should use on the WAN." }, "staticSubnetMask": { "type": "string", "description": "The subnet mask for the WAN." }, "staticGatewayIp": { "type": "string", "description": "The IP of the gateway on the WAN." }, "staticDns": { "type": "array", "items": { "type": "string" }, "description": "Up to two DNS IPs." }, "vlan": { "type": "integer", "description": "The VLAN that management traffic should be tagged with. Applies whether usingStaticIp is true or false." }, "vrf": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the VRF.", "nullable": true } }, "description": "VRF associated with the management interface. If not provided, the default VRF is used.", "nullable": true } }, "description": "WAN 2 settings (only for MX devices)" } } }, "example": { "ddnsHostnames": { "activeDdnsHostname": "mx1-sample.dynamic-m.com", "ddnsHostnameWan1": "mx1-sample-1.dynamic-m.com", "ddnsHostnameWan2": "mx1-sample-2.dynamic-m.com" }, "wan1": { "wanEnabled": "not configured", "usingStaticIp": true, "staticIp": "1.2.3.4", "staticSubnetMask": "255.255.255.0", "staticGatewayIp": "1.2.3.1", "staticDns": [ "1.2.3.2", "1.2.3.3" ], "vlan": 7, "vrf": { "name": "Mgmt-vrf" } }, "wan2": { "wanEnabled": "enabled", "usingStaticIp": false, "staticIp": "1.2.3.4", "staticSubnetMask": "255.255.255.0", "staticGatewayIp": "1.2.3.1", "staticDns": [ "1.2.3.2", "1.2.3.3" ], "vlan": 2, "vrf": { "name": "Mgmt-vrf" } } } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:write" ] } ], "summary": "Update the management interface settings for a device", "tags": [ "devices", "configure", "managementInterface" ] } }, "/devices/{serial}/reboot": { "post": { "description": "Reboot a device. This endpoint has a sustained rate limit of one request every 60 seconds.", "operationId": "rebootDevice", "parameters": [ { "name": "serial", "in": "path", "description": "Serial", "schema": { "type": "string" }, "required": true } ], "responses": { "202": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Shows the success of the reboot" } } }, "example": { "success": true } } } } }, "security": [ { "oauth2": [ "dashboard:general:config:write" ] } ], "summary": "Reboot a device", "tags": [ "devices", "liveTools" ] } } } }