MOPs API

Enterprise

List, review, and approve Methods of Procedure (MOPs) and read MOP execution history through the NetStacks Controller API.

Overview

MOPs are written and run in the NetStacks Terminal. In enterprise mode the Terminal saves them to the Controller through /api/mops and records each run under /api/mop-executions. The Admin Console's Methods of Procedure page uses the same endpoints to review and approve MOPs.

Typical API uses are listing MOPs waiting for review, approving or rejecting them from another tool, and reading execution results for reports. All endpoints need devices.access. For the MOP workflow itself, see MOPs.

MOP endpoints

Method	Path	Purpose	Permission
`GET`	`/api/mops`	List MOPs (summaries, no step data). Query: `status`, `limit`, `offset`	`devices.access`
`POST`	`/api/mops`	Create a MOP (used by the Terminal)	`devices.access`
`GET`	`/api/mops/:id`	Get a MOP, including its full `package_data`	`devices.access`
`PUT`	`/api/mops/:id`	Update a `draft` MOP	`devices.access`
`DELETE`	`/api/mops/:id`	Delete a MOP	`devices.access`
`POST`	`/api/mops/:id/submit`	Submit a draft for review (`draft` → `pending_review`)	`devices.access`
`POST`	`/api/mops/:id/review`	Approve or reject. Body: `{"approved": true, "comment": "…"}`	`devices.access`
`GET`	`/api/mops/:id/revisions`	All revisions of this MOP	`devices.access`

A MOP record has name, description, author, revision, status, risk_level, change_ticket, tags, platform_hints, estimated_duration_minutes, shared, review fields (reviewed_by, reviewed_at, review_comment), and package_data, which holds the full procedure (steps, devices, and metadata) exactly as the Terminal saved it.

Review workflow

MOP status moves through four values:

Status	Meaning	Next
`draft`	Being written. The only status that can be edited.	`POST /submit`
`pending_review`	Waiting for a reviewer	`POST /review`
`approved`	Reviewer approved	—
`rejected`	Reviewer rejected, with an optional comment	—

Find MOPs waiting for review and approve one:

# MOPs waiting for review
curl -s --cacert netstacks-ca.pem \
  "https://controller.example.com:3000/api/mops?status=pending_review" \
  -H "Authorization: Bearer $TOKEN" | jq '.[] | {id, name, author, risk_level, change_ticket}'

# Approve one
curl -s --cacert netstacks-ca.pem -X POST https://controller.example.com:3000/api/mops/4be1.../review \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"approved": true, "comment": "Approved for the Saturday window, CHG-12345"}'

The review response is the updated MOP. To change an approved or rejected MOP, the author creates a new revision in the Terminal.

Execution endpoints

An execution is one run of a MOP against its devices. The Terminal creates and drives executions; most integrations only read them.

Method	Path	Purpose	Permission
`GET`	`/api/mop-executions`	List executions. Query: `plan_id` (the MOP ID), `limit` (default 20, max 100)	`devices.access`
`GET`	`/api/mop-executions/:id`	Get one execution	`devices.access`
`GET`	`/api/mop-executions/:exec_id/devices`	Devices in the execution and their status	`devices.access`
`GET`	`/api/mop-executions/:exec_id/devices/:device_id/steps`	Steps for one device, with output and status	`devices.access`
`POST`	`/api/mop-executions`	Create an execution	`devices.access`
`PUT / DELETE`	`/api/mop-executions/:id`	Update or delete an execution	`devices.access`
`POST`	`/api/mop-executions/:id/start \| pause \| resume \| abort \| complete`	Change the execution status	`devices.access`
`POST`	`/api/mop-executions/:exec_id/devices`	Add a device	`devices.access`
`POST`	`/api/mop-executions/:exec_id/devices/:device_id/steps`	Add steps for a device	`devices.access`
`POST`	`/api/mop-executions/:exec_id/devices/:device_id/execute-phase`	Run all pending steps of one type on a device. Body: `{"step_type":"pre_check"}`	`devices.access`
`POST`	`/api/mop-executions/:exec_id/devices/:device_id/skip \| retry`	Skip or retry a device	`devices.access`
`POST`	`/api/mop-executions/:exec_id/steps/:step_id/execute \| approve \| skip`	Run, approve, or skip one step	`devices.access`

Step types are pre_check, change, post_check, and rollback. Running a step sends its command to the device over SSH using the device's connection profile, and stores the output. Every step run is written to the audit log.

Reading execution history

MOP=4be1...
# Executions of one MOP
curl -s --cacert netstacks-ca.pem "https://controller.example.com:3000/api/mop-executions?plan_id=$MOP" \
  -H "Authorization: Bearer $TOKEN"

# Devices, then step output for one device
curl -s --cacert netstacks-ca.pem https://controller.example.com:3000/api/mop-executions/$EXEC/devices \
  -H "Authorization: Bearer $TOKEN"
curl -s --cacert netstacks-ca.pem https://controller.example.com:3000/api/mop-executions/$EXEC/devices/$DEV/steps \
  -H "Authorization: Bearer $TOKEN"

Job history across features

MOP runs also appear in the cross-feature job history at GET /api/activity?category=mop. See Jobs and activity.