Conventionsv7.0.20

The Netmon API grew with the product, and it is honest about its history: most endpoints follow the patterns below, but the response envelope is not perfectly uniform across the whole surface. This chapter describes the conventions that hold in general; each endpoint entry in the reference shows the exact shape that endpoint returns, which is always authoritative over the general rule here.

Requests

Authentication. Every call outside the public handful carries a bearer token:

Authorization: Bearer <token>

Methods. The API uses GET for reads and POST for most writes and actions. A subset of the newer, RESTful resources also use PUT (update) and DELETE (remove) — alerts, outlets, routing rules, tokens, captures, and a few others. Many older write and action endpoints are POST regardless of whether they create, update, or delete; the endpoint entry always names the verb to use.

Bodies. POST/PUT requests send a JSON body with Content-Type: application/json. Send Accept: application/json as well so that validation failures come back as JSON rather than a redirect.

Path vs. body parameters. Newer resources put the identifier in the path (GET /api/captures/{id}); a number of older endpoints instead take the identifier in the POST body (for example a device_id field). The reference shows which applies for each endpoint.

Validation. Input is validated per endpoint. The fields, their types, and whether each is required are listed in every entry’s Request body table, taken from the endpoint’s own validation rules.

Responses

Success. Successful responses are JSON with a 2xx status. The body is usually one of:

• a bare object or array — the resource(s) serialized directly;
• a named wrapper — for example { "captures": [ ... ] } or { "capture": { ... } };
• a small status object — for example { "deleted": true }.

There is no single global envelope. The reference shows the real key for each endpoint; do not assume a uniform wrapper.

Lists and limits. List endpoints generally cap how much they return rather than paginating with a uniform page wrapper. Where an endpoint accepts a limit (or similar) parameter, or applies a fixed cap, the entry says so. Treat the absence of a next link as “this endpoint caps its result set” — narrow with the endpoint’s own filter parameters rather than expecting page-walking.

Encrypted fields. Secrets an endpoint stores (outlet credentials, SMTP passwords, SNMPv3 keys, and the like) are never returned in clear text. On read they are masked with a sentinel:

{ "...": "...", "password": { "__encrypted__": true } }

The sentinel means “a secret is set, and the appliance will not show it to you.” On update, send it back unchanged to keep the stored value, or send a new plain-text value to replace it. Omitting the field entirely behaves the same as replaying the sentinel — the stored secret is preserved.

Streaming endpoints

The interactive network tools (ping, MTR, and similar) have streaming variants that return text/event-stream instead of a single JSON body, emitting one data: frame per result line as it arrives:

data: {"hop":1,"host":"10.0.0.1","loss":0.0,"avg":0.4}

Consume these with a client that reads the stream incrementally — curl -N, an EventSource, or your language’s SSE support — rather than waiting for the whole response. The reference marks each streaming endpoint and shows its frame shape. Most streaming tools also have a plain-JSON sibling that returns the complete result in one response; those are easier to script and are noted alongside.

Rate limits

A few sensitive endpoints are rate-limited per client. Sign-in (POST /api/login) allows 10 requests per minute; the OAuth token endpoints allow 30 per minute; agent check-in allows 60 per minute. Exceeding a limit returns 429 Too Many Requests with a Retry-After header. The rest of the API is not separately throttled, but treat it gently — it is a monitoring appliance, not a bulk data warehouse.

A note on errors

Validation and permission failures have their own shapes, covered in Errors & Status Codes. The short version: a missing or wrong field comes back with a 4xx and a field-keyed error body (its exact shape varies by endpoint); lacking the permission for an endpoint comes back as 401 with a status/hasError/message object, not 403.