Using the Magic Suite API
Using the Magic Suite API (Application Programming Interface) means you can query Magic Suite programatically, without having to use the Magic Suite / ReportMagic user interface. The main interaction is through a REST ODATA interface so it should be possible to use most ODATA client wrappers. Full instructions for using Postman are given below.
- A Magic Suite API specific package is available to download from NuGet https://www.nuget.org/packages/MagicSuite.Api
- Examples of how to use this package are available on GitHub https://github.com/panoramicdata/ReportMagic.Api.Example
- The endpoint documentation can be found here: https://api.magicsuite.net/swagger/index.html
- If you have access to the Panoramic Data OneDrive, a set of predefined requests is available on in the Development/ReportMagic folder for import into your interface
- For help performing different actions with OData queries, please see the OData documentation: https://www.odata.org/documentation/odata-version-2-0/uri-conventions/
Using Postman to Query the Magic Suite API
Postman is a free utility that allows you to interact with different API's by creating and saving different web calls such as GET and POST. These can be grouped for better organisation. Environments are supported allowing variables to be created that allow the same defined calls to be sent to different endpoints, such as Development, Test and Live etc.Downloading Postman
To download Postman:- Download the desktop application here: https://www.getpostman.com/downloads/
- When installing, click to accept all the default settings.
- Check your email and confirm it.
- Open Postman and follow the remaining steps in Postman.
Adding a new Collection in Postman
Creating a collection in Postman allows you to group together all web calls (requests) for the Magic Suite API. The collection is the top level of grouping, but you can further group by creating folders and sub-folders. To create a collection:Adding a new Environment in Postman
Creating a new Environment in Postman means you can save values you frequently use, such as the API URL and credentials. In a shared workspace, any global variables you create and update will be available to others.To create the new environment and set up variables:
- Click on the orange '+ New' button in the top left of the Postman screen.
- On the displayed dialog, click on the 'Environment' item.
- Name the environment.
- Add an initial variable in the environment for the URL, using the variable name as shown here so that you can refer back to it later:
- For development purposes, you may want to duplicate the environment to create further environments for Test and Production.
Authentication
To interact with the Magic Suite API you must authenticate yourself via one of the following methods:API Token
An API Token can be generated for your own ReportMagic user account. To get one of these:- Go to this URL: https://docs.magicsuite.net/apitokens and click Add.
- Copy the Name and the automatically-generated Key, as you will not be able to retrieve these again.
- Click Create to create the token.
- Return to Postman and add both the token Name and Key to the environment as variables. To access the environment settings, first click on the button showing a Gear / Cog on the top right hand side of the screen:
- Then click on the ReportMagic item to show the environment variables:
- To edit the collection either right-click on the collection name (listed on the left hand side) or hover over the collection and then click on the button with the three dots. In both cases select the Edit option presented.
- In the displayed dialog click on the 'Authorization' tab.
- Change the Type to be 'Bearer Token'
- Update the Token value to one of the following:
v1 {{token_name}}/{{token_key}}v2 token:{{token_name}}/{{token_key}}
Username/Password
You can use a Base64 encoded form of your username and password for authentication. To do this follow these steps:- Open https://www.base64encode.org/ in a web browser.
- Enter your username followed by a colon followed by your password (all with no spaces):
- Click the
button to produce the Base64 encoded value: - Return to Postman and add these encoded value to the environment as a variable:
- To edit the collection either right-click on the collection name (listed on the left hand side) or hover over the collection and then click on the button with the three dots. In both cases select the Edit option presented.
- In the displayed dialog click on the 'Authorization' tab.
- Change the Type to be 'Bearer Token'
- Update the Token value to the exact following text:
v2 userpass:{{user_password}}
JWT Token
Unlike the previous two methods of authentication, this one differs in that you need to make an initial request to obtain the token.Return to Postman and add 'username', 'password' and 'token' variables to the environment. Enter credentials for the first two, but leave the token blank for the moment:
Next we need to set the authentication method for the collection. By setting it on the collection all child requests can inherit these settings, therefore requiring us to only enter this once.
- To edit the collection either right-click on the collection name (listed on the left hand side) or hover over the collection and then click on the button with the three dots. In both cases select the Edit option presented.
- In the displayed dialog click on the 'Authorization' tab.
- Change the Type to be 'Bearer Token'
- Update the Token value to the exact following text:
{{token}}
- Click on the orange '+ New' button in the top left of the Postman screen.
- On the displayed dialog, click on the 'Request' item.
- On the Request dialog enter a name for the request i.e. 'Get Token' and click the save button.
- Change the 'GET' to 'POST'
- To the right of the 'POST' enter:
{{reportmagic_api_url}}/authenticate
- Click on the 'Body' tab.
- Click on the 'raw' option.
- Click on the orange 'Text' at the right and change to 'JSON'
- Enter the following text for the body:
{ "Username": "{{username}}", "Password": "{{password}}" } - Click the blue 'Send' button to send the request for a token.
- All being well, you should receive a status 200 OK response as shown:
- Copy the accessToken value (ignoring quotes) to the clipboard.
- Click on the button in the top right that has the eye icon.
- Update the current value for the token variable and paste the token:
Creating a New Request
To add a request to fetch all Report Schedules:
- Ensure the 'ReportMagic API' collection is highlighted.
- Click on the orange '+ New' button in the top left of the Postman screen.
- Select 'Request' from the dialog.
- On the Request dialog enter a name for the request i.e. 'Get Report Schedules' and click the save button
- A new Request is created within your collection. Select the request and set the following parameters:
- Select 'GET' request type from the dropdown
- Paste the following into the request URL:
reportmagic_api_url/odata/reportschedules - Submit the request by hitting 'Send'
- If all is correct you should see the JSON encoded response:
Using Magi cSuite API Client (with JWT authentication)
- Open Visual Studio
- Create a new C# Console project that targets .Net Core
- Right-click on the project and click "Manage NuGet Packages..."
- Find the package "ReportMagic.Api" - install the latest version
using System;
using System.Threading.Tasks;
using ReportMagic.Api;
using ReportMagic.Api.Shared;
using PanoramicData.ReportMagic.Data;
namespace ApiTest
{
class Program
{
static async Task Main(string[] args)
{
// obtain a JWT bearer token for authentication
var url = "https://api.docs.magicsuite.net/";
var response = await ReportMagicClient.GetJwtAsync(url, "Email", "Password");
// create a new client instance to perform the API calls
var client = new ReportMagicClient(new ReportMagicClientOptions
{
Url = url,
AccessToken = response.AccessToken,
AuthMechanism = AuthMechanism.Jwt
});
// fetch all report schedules
var schedules = await client.GetAllAsync<ReportSchedule>();
// write all schedule names to console
foreach(var schedule in schedules)
Console.WriteLine(schedule.Name);
}
}
}Personal Connections
Personal Connections belong to a user rather than to a Tenant. Because they have no Tenant, they are not reachable through the ordinary tenant-scoped Connections OData entity set, and are served instead by a dedicated set of endpoints rooted at api/personal/connections.
All of these endpoints require an authenticated user. There is no administrative override: access is granted by ownership alone, so every endpoint operates only on the calling user's own Personal Connections. A request for a Connection belonging to somebody else returns 404 Not Found rather than 403 Forbidden, so that the existence of another user's Connection is not disclosed.
| Endpoint | Description |
|---|---|
GET api/personal/connections |
Lists the calling user's own Personal Connections, ordered by name. Passwords are removed from the response. |
POST api/personal/connections |
Creates a Personal Connection owned by the calling user. Both a Name and a Discriminator are required. |
PATCH api/personal/connections/{id} |
Updates one of the calling user's own Personal Connections. |
DELETE api/personal/connections/{id} |
Deletes one of the calling user's own Personal Connections. Returns 204 No Content. |
GET api/personal/connections/for-schedule/{reportScheduleId} |
Internal use only - see below. |
Writable properties
Only the following properties may be set on create or update: Name, Description, Url, UserName, Password, Configuration, ReadOnly, ReportMagicHasAccess and CredentialsExpiryDateTimeUtc.
Everything else is set by the server and cannot be supplied by the caller. In particular the owning user, the (always empty) Tenant, the Super Admin lock and the managed flag are not writable, so a Personal Connection cannot be reassigned to another user or promoted to a Tenant Connection through this API.
Password is write-only. It is never returned by any of these endpoints, and omitting it on a PATCH - or sending the sentinel value NOCHANGE - leaves the stored password untouched.
Error responses
| Status | Cause |
|---|---|
| 400 Bad Request | Name or Discriminator was missing on create, or the request attempted to grant AlertMagicHasAccess, ConnectMagicHasAccess or DataMagicHasAccess. Personal Connections are usable by ReportMagic only. |
| 404 Not Found | The Connection does not exist, or is not owned by the calling user. |
| 409 Conflict | The name and type clash either with a Tenant Connection visible to the user, or with another of the user's own Personal Connections. |
An attempt to modify a Personal Connection through the ordinary tenant Connections endpoint is rejected with 403 Forbidden and the message This is a personal Connection and can only be modified by its owner.
The per-schedule entitlement endpoint
GET api/personal/connections/for-schedule/{reportScheduleId} is reserved for the internal Magic Suite worker and is not part of the public API. It is called during report execution to establish which Personal Connections, if any, a given Report Schedule is entitled to use, and it is the only endpoint that returns Connection passwords - in encrypted form, for the worker to decrypt.
Any caller other than the internal worker receives 403 Forbidden:
This endpoint is only available to the internal worker.
The response reports whether use is permitted and, when it is not, why. A Schedule is entitled only where its recorded creator is the Connection's owner and both its input and output paths lie inside that user's My Files area. The reasons returned here are the text that appears in the macro errors documented on the Personal Connections page.
Reading Meraki DataMagic data
The Meraki data DataMagic collects for your tenant can be read through the REST API as read-only OData entity sets. Each set reads your tenant's own DataMagic data, and nothing in a request can reach another tenant's. The sets cannot be changed: POST, PUT, PATCH and DELETE are refused with 405 Method Not Allowed.
Who can read it
The caller needs the DataMagic read permission. Tenant administrators have it. To give it to someone else, or to the user behind an API token, add a permission of type DataMagic with Read ticked to one of their roles, on the Role Permissions page in Admin. A caller without it receives 403 Forbidden. A tenant that has no DataMagic data receives 404 Not Found with the reason.
The entity sets
| Entity set | What it holds | Date range required on |
|---|---|---|
DataMagicMerakiOrganizations | Meraki organizations DataMagic collects from | |
DataMagicMerakiNetworks | Networks, with their organization, group and tags | |
DataMagicMerakiDevices | Devices, with status, model, firmware and network | |
DataMagicMerakiDeviceHistories | Changes to each device's status and other properties over time | |
DataMagicMerakiNetworkClients | Clients seen on each network | |
DataMagicMerakiNetworkClientHistories | Client connection history by period | PeriodStart |
DataMagicMerakiNetworkEvents | Network events, such as associations, failures and DHCP issues | OccurredAt |
DataMagicMerakiNetworkEventTypes | The network event types Meraki reports | |
DataMagicMerakiWirelessHealth | Wireless health measurements per network | MeasuredAt |
DataMagicMerakiWirelessFailedConnections | Failed wireless connection attempts | OccurredAt |
DataMagicMerakiSensorData | Readings from Meraki MT sensors | MeasuredAt |
DataMagicMerakiAccessPointSsids | SSIDs broadcast by each access point | |
DataMagicMerakiApplianceVlans | VLANs configured on security appliances | |
DataMagicMerakiConfigTemplates | Configuration templates | |
DataMagicMerakiConfigurationChanges | The Meraki configuration change log | |
DataMagicMerakiFloorPlans | Floor plans per network | |
DataMagicMerakiPorts | Switch ports and their status | |
DataMagicMerakiVpnPeers | Site-to-site VPN peers and their reachability | |
DataMagicMerakiWanInterfaceUsage | WAN uplink usage | |
DataMagicMerakiMacVendors | MAC address vendors and their priorities | |
DataMagicMerakiSubscriptions | Meraki subscriptions | |
DataMagicMerakiSubscriptionEntitlements | Entitlements within each subscription | |
DataMagicMerakiCotermLicenses | Co-termination licenses | |
DataMagicMerakiOrganizationLicenses | Per-device licenses, with state, claim, activation and expiry dates | |
DataMagicMerakiEoxes | Cisco end-of-sale and end-of-support dates for each device model | |
DataMagicMerakiSensorDataAggregations | Hourly roll-ups of MT sensor readings: count, sum, minimum, maximum and mean | MeasuredAtHour |
DataMagicMerakiWebHookEvents | Meraki alerts received by webhook, such as devices going down or coming back; the raw alert payload is not returned |
The Swagger page of your environment lists every property of every set.
Querying
Each set supports $filter, $select, $orderby, $top, $skip, $count and $expand (one level). For example:
GET https://api.magicsuite.net/odata/DataMagicMerakiDevices?$filter=Status eq 'offline'&$select=Name,Serial,NetworkName,Status GET https://api.magicsuite.net/odata/DataMagicMerakiNetworks?$filter=contains(Name,'Branch')&$orderby=Name GET https://api.magicsuite.net/odata/DataMagicMerakiDevices(5b0f0c1e-6a43-4c39-9d0e-0b1f2c3d4e5f)
Ids are GUIDs. Credentials DataMagic holds, such as an organization's Meraki API key and SNMP community, are never returned.
Limits
- Paging: a response holds at most 1,000 rows. When there are more, it carries an
@odata.nextLink; request that link to read the next page, until a response has none. This applies whatever$topasks for. - Date range: the sets with a date column in the table above are stored by day, so every query of them must give a range on that column, at most 31 days long, for example
$filter=OccurredAt ge 2026-10-01T00:00:00Z and OccurredAt lt 2026-10-08T00:00:00Z. Other conditions may be added withand. A query without a range is refused with400 Bad Requestnaming the column. Look up by id is not offered on these sets; filter onIdwithin a date range instead. - Time: a single query may run for at most 30 seconds.
Hourly roll-ups
Two functions return hourly counts from DataMagic's roll-up tables, over a range of at most 31 days. Every parameter must be given; use null for a filter you do not want, and [] for all types.
GET https://api.magicsuite.net/odata/DataMagicMerakiNetworkEvents/GetNetworkEventAggregations(startDateTime=2026-10-01T00:00:00Z,endDateTime=2026-10-08T00:00:00Z,groupBy='TimeSeriesByNetwork',types=[],organizationName=null,networkGroup=null,networkNameStartsWith=null,networkMerakiId=null,macVendorPriorityGe=null,take=null) GET https://api.magicsuite.net/odata/DataMagicMerakiNetworkClientHistories/GetNetworkClientHistoryAggregations(startDateTime=2026-10-01T00:00:00Z,endDateTime=2026-10-02T00:00:00Z,groupBy='TimeSeriesByNetwork',types=[],organizationName=null,networkGroup=null,networkNameStartsWith='Branch',networkMerakiId=null,take=null)
Network event groupBy values: TimeSeriesOverall, TimeSeriesByEventType, TimeSeriesByOrganization, TimeSeriesByNetwork, TimeSeriesByNetworkGroup, TimeSeriesByMacVendorPriority, EventTypesByOrganization, EventTypesByNetwork, EventTypesByNetworkGroup, EventTypesByMacVendorPriority. Client history groupBy values: TimeSeriesOverall, TimeSeriesByAggregationType, TimeSeriesByOrganization, TimeSeriesByNetwork, TimeSeriesByNetworkGroup. take keeps only that many of the largest series.
From .NET
The MagicSuite.Api NuGet package reads these sets with typed models, following the next links for you:
using var client = new MagicSuiteClient(new MagicSuiteClientOptions { Url = "https://api.magicsuite.net", ApiTokenName = name, ApiTokenKey = key });
// Every offline device
var offline = await client.GetAllDataMagicMerakiAsync<DeviceDto>(new DataMagicMerakiQuery { Filter = "Status eq 'offline'" }, cancellationToken);
// A week of network events, one page in memory at a time
await foreach (var networkEvent in client.EnumerateDataMagicMerakiAsync<NetworkEventDto>(new DataMagicMerakiQuery
{
Filter = "OccurredAt ge 2026-10-01T00:00:00Z and OccurredAt lt 2026-10-08T00:00:00Z"
}, cancellationToken))
{
// ...
}
// Hourly event counts per network
var counts = await client.GetDataMagicMerakiNetworkEventAggregationsAsync(start, start.AddDays(7), NetworkEventsViewMode.TimeSeriesByNetwork, new DataMagicMerakiAggregationFilter(), cancellationToken);
The same data is available from the command line with magicsuite api get and magicsuite api aggregate; see the Command Line Interface (CLI) page.
