canonical: https://jentic.com/apis/gambitcomm.local/mimic

# Gambitcomm MIMIC REST API

The MIMIC REST API is the programmatic control surface for Gambit Communications' MIMIC simulator, the industry-standard tool for simulating thousands of SNMP, IPMI, NetFlow, sFlow, IoT, and Telnet/SSH devices for network management testing. The 356 endpoints under /mimic let test engineers create simulated agents, configure protocol behaviour, control logging and statistics, manage simulator clients, and orchestrate large-scale lab scenarios from CI pipelines. Authentication uses HTTP basic credentials and the simulator runs locally so the base URL points at 127.0.0.1. The API is targeted at NMS vendors, network operators, and IoT platform builders who need to validate management software against device populations far larger than physical lab inventory allows.

## For AI agents

Drive Gambit Communications' MIMIC network device simulator over 356 REST endpoints to spin up SNMP, IPMI, IoT, and Telnet simulated agents and orchestrate large lab scenarios from automation.

## Scope

Does not handle real device management, production network monitoring, or telemetry ingestion - use for controlling Gambit Communications' MIMIC device simulator only.

## Capabilities

- Query simulator state including version, last log entries, and connected client list via `/mimic/get`/* operations
- Inspect and modify simulator configuration through cfgfile and cfgfile_changed checks
- Drive simulated SNMP, IPMI, IoT, and Telnet agents from CI by issuing /mimic/* control calls
- Track per-client and per-session statistics via the `/mimic/get/clients` and related telemetry endpoints
- Authenticate every simulator request with HTTP basic credentials so multi-tenant labs are isolated
- Retrieve simulator logs programmatically via `/mimic/get/log` for debugging failed test runs

## Use cases

### Continuous Integration of NMS Software

Add simulated network device coverage to a CI pipeline by calling the MIMIC REST API to start, configure, and tear down simulated SNMP agents alongside the NMS software under test. The 356 control endpoints mean tests can replicate populations of thousands of devices without physical hardware, catching regressions earlier.

Example prompt: Call `/mimic/get/version`, then start the configured scenario, run the NMS test suite, and tear the simulator down via the matching control endpoint.

### Large-Scale IoT Device Simulation

Spin up tens of thousands of simulated IoT and IPMI devices for performance and scale testing of an IoT platform by orchestrating MIMIC scenarios from a control plane. The REST surface lets engineers script the same scenario across multiple simulator hosts.

Example prompt: Issue control calls under /mimic to start the IoT scenario, then poll `/mimic/get/clients` to confirm the expected device count is online.

### Lab Configuration Drift Detection

Detect drift in a long-running lab by polling `/mimic/get/cfgfile_changed` and `/mimic/get/cfgfile` so any unexpected configuration change in the simulator is logged and alerted. Catching drift early keeps test results reproducible across CI runs.

Example prompt: Poll GET `/mimic/get/cfgfile_changed` every minute and emit an alert when the response indicates a change since the last known checksum.

### Agent-Driven Test Orchestration via Jentic

An NMS-test agent receives a request like 'spin up the 1000-device SNMP scenario and run the regression suite' and uses Jentic to discover the right /mimic control endpoints, load their schemas, and execute them with credentials from the vault. Jentic isolates the simulator credentials so the agent's prompt stays clean.

Example prompt: Search Jentic for 'list mimic clients', load `/mimic/get/clients`, and execute it after starting the scenario to confirm the simulated devices are connected.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/mimic/get/version` | Get the MIMIC simulator version |
| GET | `/mimic/get/max` | Get the maximum number of agents supported |
| GET | `/mimic/get/clients` | List currently connected simulator clients |
| GET | `/mimic/get/cfgfile` | Read the active simulator config file metadata |
| GET | `/mimic/get/cfgfile_changed` | Check whether the config file has changed |
| GET | `/mimic/get/log` | Read the simulator log buffer |
| GET | `/mimic/get/return` | Get the return code of the last simulator command |
| GET | `/mimic/get/last` | Read the last simulator action result |

## Key resources

- **Simulator State** — Read-only endpoints under `/mimic/get`/* exposing version, max agents, last log lines, and config file metadata.
- **Clients** — Inspect simulator clients and connections via `/mimic/get/clients.`
- **Logs** — Retrieve simulator log output via `/mimic/get/log.`
- **Configuration** — Inspect cfgfile and cfgfile_changed status to detect lab drift.

## Why Jentic

- **Setup:** Wiring the MIMIC REST API by hand means setting up HTTP basic auth against the local simulator host at 127.0.0.1 and mapping its many get and set simulator-control calls yourself. Through Jentic you install once, import the MIMIC REST API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** MIMIC exposes simulator get and set operations rather than per-resource URL paths, so scope this by operation: limit the agent to the operations it needs, such as reading the version, client list, or log, and leave state-changing set operations out of the allowed set. Every operation the agent can run is one you chose to include.
- **Credential handling:** Your MIMIC basic-auth credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get the MIMIC simulator version' or 'read the simulator log', and Jentic returns the matching MIMIC operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ngrok API** — Tunnelling service often used to expose a local MIMIC simulator host to remote CI runners.
- **Microsoft Graph API** — Real device and identity management API for Microsoft-managed endpoints, contrasting with MIMIC's simulator-only scope.

## FAQ

### What authentication does the MIMIC REST API use?

MIMIC uses HTTP basic authentication (basicAuth in the spec) - every request carries an Authorization header with username and password configured on the simulator host. Through Jentic, the credentials are held encrypted in the vault so the agent never sees them.

### Can I list connected clients on a running MIMIC simulator?

Yes. GET `/mimic/get/clients` returns the simulator's currently connected clients so test orchestration can confirm the expected device count is online before running assertions.

### What are the rate limits for the MIMIC REST API?

MIMIC runs on a local lab host (the spec lists 127.0.0.1 as the server) and the OpenAPI document does not declare numeric rate limits across the 356 endpoints. Throughput is bounded by simulator host capacity rather than a published quota.

### How do I check if a MIMIC config file has changed through Jentic?

Run a Jentic search for 'check mimic cfgfile changed', load GET `/mimic/get/cfgfile_changed`, and execute it on a polling loop to detect drift. Get started with Jentic One, the self-hosted execution layer.

### Does MIMIC simulate protocols beyond SNMP?

Yes. The simulator covers SNMP, IPMI, NetFlow, sFlow, Telnet, SSH, and a broad set of IoT protocols, all controllable through the same /mimic REST surface so a single test harness can drive heterogeneous device populations.

### Can I limit what my agent is allowed to do with the MIMIC REST API?

Yes. Because you run Jentic One yourself, your own rules decide which MIMIC operations and credentials the agent may use, and MIMIC is scoped by operation rather than by URL path. You can allow only the read operations the agent needs, such as GET `/mimic/get/version`, GET `/mimic/get/clients`, and GET `/mimic/get/log`, while leaving the state-changing set operations out of the allowed set. Every simulator operation the agent can call is one you chose to include.