Skip to main content

 

Cisco Meraki Documentation

Cisco Meraki Dashboard API

Overview

Learn more with these free online training courses on the Meraki Learning Hub:

Sign in with your Cisco SSO or create a free account to start training.

The Meraki dashboard Application Programming Interface (API) is an interface for software to interact directly with the Meraki cloud platform and Meraki-managed devices. The API contains a set of tools known as "endpoints" for building software and applications that communicate with the Meraki dashboard. Use cases include provisioning, bulk configuration changes, monitoring, and role-based access controls. The dashboard API is a modern, RESTful API using HTTPS requests to a URL and JSON as a human-readable format. The dashboard API is an open-ended tool that can be used for many purposes. Here are some examples of how it is used today by Meraki customers:

  • Add new organizations, admins, networks, devices, VLANs, Service Set Identifiers (SSIDs)
  • Provision thousands of new sites in minutes with an automation script
  • Automatically onboard and off-board new employees' teleworker device(s)
  • Build your own dashboard for store managers, field techs, or unique use cases

Note: API call volume is rate-limited to ten calls per second, per organization.

API Documentation

For more information on Meraki's APIs, please visit our dedicated API documentation website: Meraki Developer Hub

The API reference documentation is provided in a Postman collection accessible at our Meraki Developer Hub > Resources > Postman Collections website. The Postman collection can be imported into the Postman application to test API calls.

Generate API Key

Cisco Meraki Dashboard API is enabled by default on all organizations.
To generate an API key, go to the My Profile page accessed via the avatar icon in the top right-hand corner of dashboard. This API key will be associated with the dashboard administrator account which generates it and will inherit the same permissions as that account. You can generate, revoke, and regenerate your API key on your profile.

Note: Keep your API key safe as it provides authentication to all of your organizations with the API enabled. Dashboard does not store API keys in plaintext for security reasons, so this is the only time you will be able to record it. If you lose or forget your API key, you will have to revoke it and generate a new one.

Image of "My Profile" page and "Generate API key" button

Image of new API key and confirmation message

Note: there is a limit of only two API keys per profile. After generating two keys, the "Generate API key" disappears from the dashboard view. You need to revoke one of the generated keys before you can generate a new one. 

Note: SAML dashboard administrators cannot view or generate API keys. Please note that this means that Single Sign On (SSO) users will not be able to generate API keys. 

API & Webhooks Dashboard page

API keys and Webhooks can also be configured via the dedicated API & Webhooks Dashboard UI page. Navigate to  Organization → Configure → API & Webhooks. 

org_admin.png

 

The 3 tabs on the API & Webhooks page are as follows:

  • API analytics
  • API keys and access
  • Webhooks

Note: This page is currently visible only to organization administrators.

API Analytics Overview

API Analytics equips organizations with visibility into their dashboard API consumption so they can understand which integrations or custom applications are interacting with their environment programmatically, and so developers building those applications can get detailed insights into how well their applications are performing and further optimize their applications.

The data displayed on this page originates from the following API operations:

Accessing API Analytics

When you log into the Meraki dashboard, hover over Organization on the left navigation. 

Under Configure, select API & Webhooks. API analytics is the first tab you land on.

This page is visible to all org admins.

api webhooks page

Modules

There are 3 modules (sections) on the page, which serve to help you monitor your organization’s API consumption.

The data on this page will only update when the page is refreshed.

Overview Cards

The Overview section provides at-a-glance summary cards to help affirm your overall applications’ health over the last 24 hours

  • The number of total requests and their breakdowns
  • The number and relative percentage of successful requests  
  • The number and relative percentage of rate limit hits (HTTP responses with 429 codes) 
  • The number and relative percentage of other errors (HTTP responses with 400 codes except 429) 
    • You can also see the relative percentage change from the previous day to understand how any errors may have increased or decreased. 
  • Only fully processed API requests are logged. API requests that fail to reach Meraki dashboard will not be reported here.
  • The relative percentage change from the previous day is calculated as: the sum of errors over the most recent 24 hours minus the sum of errors over the preceding 24 hours, divided by the sum of errors over the preceding 24 hours, multiplied by 100.

Trends Graph

trends_graph.png

The Trends section provides a line graph to visualize your integrations and custom applications’ API usage over time.

The line graph consists of 3 lines: 

  • Green depicts successful requests (those with HTTP response codes between 200 and 399, inclusive),  
  • Red depicts responses that exceeded the rate limit (those with HTTP response code 429), and  
  • Yellow depicts other application error responses (those with HTTP response codes between 400 and 499, inclusive, excluding 429).  

When you hover over a specific point on the graph, you will see the total request count. Specific HTTP response codes will show for the yellow line. For more descriptive info on what these response codes mean, refer to documentation on HTTP response status codes.

You may also dive deeper and filter the graph to show responses from applications authorized by specific admins or specific response codes, by selecting the dropdown filters. 

Use the time-picker to select the start/end date and time (UTC) for the graph. The maximum selectable timespan is 30 days.  

date_picker.png

Metrics Table

metrics_table_api_analytics.png

The Metrics section provides top usage metrics by: 

  • Applications, which might be custom applications/scripts or partner integrations.
  • Operations, which are specific actions an application can take in dashboard API.
  • Admins, whose API key the application uses.

Each tab summarizes the number of requests, successes, errors, success rate, and relative percentage of total requests that line comprises. 

The status icons next to success rate indicate areas that potentially require attention. 

  • A red status icon signifies a failure rate of 80% and above. These applications warrant the most investigation and remediation. 
  • A yellow status icon signifies that 20-80% of the application’s calls are succeeding. These applications can be optimized to consume the API budget more efficiently.  
  • A green status icon signifies a success rate of 80% and above. 

Use the time picker to select the start/end date and time (UTC) for the table. The maximum selectable timespan is 30 days

time_picker_2.png

Download (CSV Export)

If you would like to dive deeper into the data, you can download the full request history logs. Download generates a CSV file with API consumption data for you to do your own analysis. 

Common use cases for diving deeper in the CSV include troubleshooting failed API requests, analyzing usage trends to optimize performance, auditing API access for suspicious activity, and debugging custom apps/scripts. 

The Download detailed logs button is at the top right of the page. Make data filter selections before you click download. 

Only the most recent 100,000 requests will be exported. If you believe the time interval you selected may contain more, reduce the interval. Data retrieval could take several minutes – do not refresh or exit the API analytics page while download is in progress.

csv_export_api_analytics.png

The following data columns are in the CSV export: 

  • Admin ID 
  • Amin Name 
  • Admin Email 
  • HTTP Method 
  • Host 
  • Path 
  • Query String 
  • User Agent 
  • Time stamp 
  • HTTP Response Code 
  • Source IP 
  • API Version 
  • Operation ID

Using the Dashboard API

API Requests

Every request must specify an API key via a request header. Furthermore, the API version must be specified in the URL. The API will return 404 (rather than a 403) in response to a request with a missing or incorrect API key in order to prevent leaking the existence of resources to unauthorized users.

X-Cisco-Meraki-API-Key: <secret key>

The API version must be specified in the URL:

https://api.meraki.com/api/v1/<resource>

For organizations hosted in the China dashboard, use api.meraki.cn

For organizations hosted in the Canada dashboard, use api.meraki.ca

For organizations hosted in the India dashboard, use api.meraki.in

For organizations hosted in the Government dashboard, use api.gov-meraki.com

Once an API version is released, we will make only backwards-compatible changes to it. Backwards-compatible changes include:

  • Adding new API resources
  • Adding new optional request parameters to existing API methods

  • Adding new properties to existing API responses

  • Changing the order of properties in existing API responses

Identifiers in the API are opaque strings. A <network_id>, for example, might be the string “126043”, whereas an <order_id> might contain characters, such as “4S1234567”. Client applications must not try to parse them as numbers. Even identifiers that look like numbers might be too long to encode without loss of precision in Javascript, where the only numeric type is IEEE 754 floating point.

 

Verbs in the API follow the usual REST conventions:

  • GET returns the value of a resource or a list of resources, depending on whether an identifier is specified.
    • GET of /v1/organizations returns a list of organizations
    • GET of /v1/organizations/<org_id> returns a particular organization
  • POST adds a new resource
    • POST to /v1/organizations/<org_id>/admins
    • POST performs other non-idempotent changes 
  • PUT updates a resource
    • PUT is idempotent; it updates a resource, but does not create a resource if it does not already exist, which differs from RFC 9110
    • PUT should specify all the fields of a resource; omitted fields will have no changes made to their value
  • DELETE removes a resource

Note: Call volume is limited to ten calls per second, per organization.

POST /api/v1/organizations/{organizationId}/inventory/claim
POST /api/v1/organizations/{organizationId}/claim
POST /api/v1/networks/{networkId}/devices/claim

These API endpoints will now be subject to a stricter rate limit of 10 requests over a 5 minute period, per IP address. When this rate limit has been reached, similar to the existing Dashboard API rate limiting, an HTTP 429 error will be returned and the Retry-After response header will be set to the number of seconds required to wait to access the endpoint again.

Status and Error Codes

Responses from the API generally use standard RFC 9110 HTTP Status Codes. Some examples:

  • 400: Bad Request - You did something wrong, for example, a malformed request or missing parameter
  • 401: Unauthorized - Invalid API Key
  • 403: Forbidden - You don't have permission to do that
  • 404: Not found - No such URL or you don't have access to the API or organization at all
  • 429: Too Many Requests - You submitted more than ten calls in one second to an organization, triggering rate limiting. This also applies for API calls made across multiple organizations that triggers rate limiting for one of the organizations.

If the response code is not specific enough to determine the cause of the issue, error messages will be included in the response in JSON format, for example:

{
    "errors": [
       "VLANs are not enabled for this network"
    ]
}

Read only administrators will only be allowed to make GET requests. Any other requests will result in 403: Forbidden 

Examples

Below is a list of example requests and responses. Please note that these are not comprehensive; for a comprehensive list of API endpoints and their details, please see the online documentation here: Meraki Developer Hub.

Organizations

Retrieve the list of organizations for the API key specified in X-Cisco-Meraki-API-Key:

GET https://api.meraki.com/api/v1/organizations
Response code: 200
Response body: [{"id":"<org_id>","name":"<org_name>" }]

Retrieve metadata about a specific organization:

GET https://api.meraki.com/api/v1/organizations/<org_id>
Response code: 200
Response body: { "id": <org_id>, "name": "Test Organization" }

Most HTTP libraries and clients will only follow a redirect with the HTTP verb GET. If using other HTTP verbs, they may still follow the redirect, but they will substitute the other HTTP verb with GET.  As a result, you may find a redirect on DELETE, POST, or PUT will look as though a GET was requested. To avoid this, follow the steps below:

  1. Perform a GET on the organization you are working with
  2. Store the URL you are working with
  3. Use the URL for subsequent requests (particularly those that modify state).

Create a new organization:

POST https://api.meraki.com/api/v1/organizations
Request body: { “name”: “Second Test Organization” }
Response code: 201 
Response body: { "id": <new_org_id>, name: "Second Test Organization" }

The new organization will be unconfigured. However, the admin who created it will have full organization write access. Clients of the API can add additional admins and then remove the creating admin from the new organization if desired.

Note: The API will not allow clients to remove the last remaining admin with full organization write access. Doing so could lead to an unconfigurable organization. 

Networks

List the networks in an organization: 

GET https://api.meraki.com/api/v1/organizations/<new_org_id>/networks
Response code: 200
Response body: [ { "id": <network_id>, "name": "Test Network", "organization_id": <new_org_id>, "type": "wireless",
   "timeZone": "America/Los_Angeles", "tags": " test "}]

Create a new network:

POST https://api.meraki.com/api/v1/organizations/<org_id>/networks
Request body: { “name”: “Test Network 2”, “organizationId”: <org_id>, “type”: “appliance”}
Response code: 201
Response body: { “id”: <network_id>, “name”: “Test Network 2”, “organization_id”: <org_id>, “type”: “appliance”, “tags”: null }

Valid network types are appliance, switch, wireless, systemsManager or camera. Use a combination of these to create a combined network. For example, “type”: “appliance wireless”

Licenses and Devices

Claim a device, license key, or order into an organization. When claiming by order, all devices and licenses in the order will be claimed. Licenses will be added to the organization and devices will be placed in the organization's inventory. These three types of claims are mutually exclusive and cannot be performed in one request. The licenseMode parameter can be either renew or addDevices. addDevices will increase the license limit while renew will extend the amount of time until expiration. This parameter is required when claiming by licenseKey. Please see this article for more information.

POST https://api.meraki.com/api/v1/organizations/<org_id>/ claim
Request body: { "order": "4CXXXXXXX" }
Response code: 200
Response body: <empty>

Simple Network Management Protocol (SNMP) Settings

Set the SNMP settings for an organization. The community string for SNMPv2 is in the response. It can also be retrieved via a GET to this same URL.

GET https://api.meraki.com/api/v1/organizations/<org_id>/snmp
Request body: { "v2cEnabled": true, "v3Enabled": true, "v3AuthMode": "SHA", "v3AuthPass", <secret>, "v3PrivMode": "AES128", "v3PrivPass": <secret>, "allowedIPs": ["5.6.7.8"] }
Response code: 200
Response body: { "v2Enabled": true, “v2CommunityString”: <secret>, "v3Enabled": true, "authMode": "SHA", "authPass", <secret>, "privMode": "AES128", "privPass": <secret>, "allowedIPs": ["5.6.7.8"] }

Administrators 

List the administrators for an organization:

GET https://api.meraki.com/api/v1/organizations/<org_id>/admins
Response code: 200
Response body: [ { "name": "Jane Doe", "email": "jane@doe.com", "orgAccess": "full","id": <admin_id> } ]

Organization access can be full, read-only, or none.
 

Add a new administrator with rights to only one network:

POST https://api.meraki.com/api/v1/organizations/<org_id>/admins/
Request body: { "name": "John Doe", "email": "john@doe.com", "orgAccess": "none", "networks": [{ "id": <network_id>, "access": "full" }
Response code: 201
Response body: { “id”: <admin_id>, "name": "John Doe", "email": "john@doe.com", "orgAccess": "none", "networks": [{ "id": <network_id>, "access": "full" }]

Valid access levels for networks are full, read-only, monitor-only, and guest-ambassador. Clients can also give administrators access by tag by substituting the networks field for tags such as:

"tags": [{ "tag": "foo", "access": "read-only" }],

Valid access levels for tags are the same as for networks. Clients can update administrators using PUT and specifying an admin_id.

Delete an administrator:

DELETE https://api.meraki.com/api/v1/organizations/<org_id>/admins/<admin_id>
Response code: 204
Response body: <empty>