Mist Sites Marvis Configs API

openapi: 3.1.0
info:
  contact:
    email: tmunzer@juniper.net
    name: Thomas Munzer
  description: '> Version: **2606.1.1**

    >

    > Date: **July 10, 2026**

    <div class="notification"> NOTE:<br>Some important API changes will be introduced. Please make sure to read the <a href="https://www.juniper.net/documentation/us/en/software/mist/api/http/guides/important-api-changes">announcements</a> </div>


    ---

    ## Additional Documentation

    * [Mist Automation Guide](https://www.juniper.net/documentation/us/en/software/mist/automation-integration/index.html)

    * [Mist Location SDK](https://www.juniper.net/documentation/us/en/software/mist/location-services/topics/concept/mist-how-get-mist-sdk.html)

    * [Mist Product Updates](https://www.juniper.net/documentation/us/en/software/mist/product-updates/)


    ## Helpful Resources

    * [API Sandbox and Exercises](https://api-class.mist.com/)

    * [Postman Collection, Runners and Webhook Samples](https://www.postman.com/juniper-mist/workspace/mist-systems-s-public-workspace)

    * [Python Script Examples](https://github.com/tmunzer/mist_library)

    * [API Demo Apps](https://apps.mist-lab.fr/)

    * [Juniper Blog](https://blogs.juniper.net/)


    ## Mist Web Browser Extension:

    * Google Chrome, Microsoft Edge and other Chromium-based browser: [Chrome Web Store](https://chromewebstore.google.com/detail/mist-extension/ejhpdcljeamillfhdihkkmoakanpbplh)

    * Firefox: [Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/mist-extension/)


    ---'
  license:
    name: MIT
    url: https://raw.githubusercontent.com/tmunzer/Mist-OAS3.0/main/LICENSE
  title: Mist Admins Sites Marvis Configs API
  version: 2606.1.1
  x-logo:
    altText: Juniper-MistAI
    backgroundColor: '#FFFFFF'
    url: https://www.mist.com/wp-content/uploads/logo.png
servers:
- description: Mist Global 01
  url: https://api.mist.com
- description: Mist Global 02
  url: https://api.gc1.mist.com
- description: Mist Global 03
  url: https://api.ac2.mist.com
- description: Mist Global 04
  url: https://api.gc2.mist.com
- description: Mist Global 05
  url: https://api.gc4.mist.com
- description: Mist EMEA 01
  url: https://api.eu.mist.com
- description: Mist EMEA 02
  url: https://api.gc3.mist.com
- description: Mist EMEA 03
  url: https://api.ac6.mist.com
- description: Mist EMEA 04
  url: https://api.gc6.mist.com
- description: Mist APAC 01
  url: https://api.ac5.mist.com
- description: Mist APAC 02
  url: https://api.gc5.mist.com
- description: Mist APAC 03
  url: https://api.gc7.mist.com
security:
- apiToken: []
- csrfToken: []
tags:
- description: Marvis Config Actions are config changes injected by Marvis into network devices. These actions can be searched, counted, deleted, and given feedback.
  name: Sites Marvis Configs
paths:
  /api/v1/sites/{site_id}/marvis_configs/count:
    parameters:
    - $ref: '#/components/parameters/site_id'
    get:
      description: Count Marvis Config Actions for a site by a distinct field.
      operationId: countSiteMarvisConfigActions
      parameters:
      - description: 'Field to count by. enum: `mac`, `type`, `src`, `admin_id`, `op`, `port_id`, `reason`, `vlan_ids`'
        in: query
        name: distinct
        schema:
          default: mac
          type: string
      - description: Filter by device MAC address
        in: query
        name: mac
        schema:
          type: string
      - description: Filter by config type (e.g. wired)
        in: query
        name: type
        schema:
          type: string
      - description: Filter by source of the config action (e.g. marvis)
        in: query
        name: src
        schema:
          type: string
      - description: Filter by admin ID
        in: query
        name: admin_id
        schema:
          type: string
      - description: Filter by operation type (e.g. disable_port, enable_port, update_mtu, add_vlans_to_port)
        in: query
        name: op
        schema:
          type: string
      - description: Filter by port identifier (e.g. ge-0/0/13)
        in: query
        name: port_id
        schema:
          type: string
      - description: Filter by VLAN ID
        in: query
        name: vlan_ids
        schema:
          type: integer
      - description: Filter by reason for the config action (e.g. rogue_dhcp_server_detected)
        in: query
        name: reason
        schema:
          type: string
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/end'
      - $ref: '#/components/parameters/duration'
      responses:
        '200':
          $ref: '#/components/responses/MarvisConfigActionsCount'
        '400':
          $ref: '#/components/responses/HTTP400'
        '401':
          $ref: '#/components/responses/HTTP401'
        '403':
          $ref: '#/components/responses/HTTP403'
        '404':
          $ref: '#/components/responses/HTTP404'
        '429':
          $ref: '#/components/responses/HTTP429'
      summary: countSiteMarvisConfigActions
      tags:
      - Sites Marvis Configs
  /api/v1/sites/{site_id}/marvis_configs/search:
    parameters:
    - $ref: '#/components/parameters/site_id'
    get:
      description: Search Marvis Config Actions for a site.
      operationId: searchSiteMarvisConfigActions
      parameters:
      - description: Filter by device MAC address
        in: query
        name: mac
        schema:
          type: string
      - description: Filter by config type (e.g. wired)
        in: query
        name: type
        schema:
          type: string
      - description: Filter by source of the config action (e.g. marvis)
        in: query
        name: src
        schema:
          type: string
      - description: Filter by admin ID
        in: query
        name: admin_id
        schema:
          type: string
      - description: Filter by operation type (e.g. disable_port, enable_port, update_mtu, add_vlans_to_port)
        in: query
        name: op
        schema:
          type: string
      - description: Filter by port identifier (e.g. ge-0/0/13)
        in: query
        name: port_id
        schema:
          type: string
      - description: Filter by VLAN ID
        in: query
        name: vlan_ids
        schema:
          type: integer
      - description: Filter by reason for the config action (e.g. rogue_dhcp_server_detected)
        in: query
        name: reason
        schema:
          type: string
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/end'
      - $ref: '#/components/parameters/duration'
      responses:
        '200':
          $ref: '#/components/responses/MarvisConfigActionsSearch'
        '400':
          $ref: '#/components/responses/HTTP400'
        '401':
          $ref: '#/components/responses/HTTP401'
        '403':
          $ref: '#/components/responses/HTTP403'
        '404':
          $ref: '#/components/responses/HTTP404'
        '429':
          $ref: '#/components/responses/HTTP429'
      summary: searchSiteMarvisConfigActions
      tags:
      - Sites Marvis Configs
  /api/v1/sites/{site_id}/marvis_configs/{id}:
    parameters:
    - $ref: '#/components/parameters/site_id'
    - description: UUID of the Marvis Config Action
      in: path
      name: id
      required: true
      schema:
        format: uuid
        type: string
    delete:
      description: Delete a Marvis Config Action.
      operationId: deleteSiteMarvisConfigAction
      responses:
        '200':
          $ref: '#/components/responses/OK'
        '400':
          $ref: '#/components/responses/HTTP400'
        '401':
          $ref: '#/components/responses/HTTP401'
        '403':
          $ref: '#/components/responses/HTTP403'
        '404':
          $ref: '#/components/responses/HTTP404'
        '429':
          $ref: '#/components/responses/HTTP429'
      summary: deleteSiteMarvisConfigAction
      tags:
      - Sites Marvis Configs
  /api/v1/sites/{site_id}/marvis_configs/{id}/feedback:
    parameters:
    - $ref: '#/components/parameters/site_id'
    - description: UUID of the Marvis Config Action
      in: path
      name: id
      required: true
      schema:
        format: uuid
        type: string
    post:
      description: Submit feedback on a Marvis-injected config action (e.g. mark as invalid).
      operationId: submitSiteMarvisConfigFeedback
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/marvis_config_feedback'
        description: Request Body
        required: true
      responses:
        '200':
          $ref: '#/components/responses/MarvisConfigFeedbackResponse'
        '400':
          $ref: '#/components/responses/HTTP400'
        '401':
          $ref: '#/components/responses/HTTP401'
        '403':
          $ref: '#/components/responses/HTTP403'
        '404':
          $ref: '#/components/responses/HTTP404'
        '429':
          $ref: '#/components/responses/HTTP429'
      summary: submitSiteMarvisConfigFeedback
      tags:
      - Sites Marvis Configs
components:
  responses:
    OK:
      description: OK
    HTTP400:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP400Example'
          schema:
            $ref: '#/components/schemas/response_http400'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP400Example'
          schema:
            $ref: '#/components/schemas/response_http400'
      description: Bad Syntax
    HTTP403:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP403Example'
          schema:
            $ref: '#/components/schemas/response_http403'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP403Example'
          schema:
            $ref: '#/components/schemas/response_http403'
      description: Permission Denied
    MarvisConfigActionsSearch:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/MarvisConfigActionsSearchExample'
          schema:
            $ref: '#/components/schemas/marvis_config_actions_search'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/MarvisConfigActionsSearchExample'
          schema:
            $ref: '#/components/schemas/marvis_config_actions_search'
      description: Paginated Marvis Config Actions search results
    MarvisConfigFeedbackResponse:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/MarvisConfigFeedbackResponseExample'
          schema:
            $ref: '#/components/schemas/marvis_config_feedback_response'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/MarvisConfigFeedbackResponseExample'
          schema:
            $ref: '#/components/schemas/marvis_config_feedback_response'
      description: Marvis Config Feedback response
    MarvisConfigActionsCount:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/CountExample'
          schema:
            $ref: '#/components/schemas/response_count'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/CountExample'
          schema:
            $ref: '#/components/schemas/response_count'
      description: Count result
    HTTP404:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/response_http404'
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/response_http404'
      description: Not found. The API endpoint doesn’t exist or resource doesn’ t exist
    HTTP429:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP429Example'
          schema:
            $ref: '#/components/schemas/response_http429'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP429Example'
          schema:
            $ref: '#/components/schemas/response_http429'
      description: Too Many Request. The API Token used for the request reached the 5000 API Calls per hour threshold
    HTTP401:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP401Example'
          schema:
            $ref: '#/components/schemas/response_http401'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP401Example'
          schema:
            $ref: '#/components/schemas/response_http401'
      description: Unauthorized
  examples:
    MarvisConfigActionsSearchExample:
      value:
        end: 1775122221
        limit: 10
        results:
        - admin_id: 6d617276-0000-0000-3157-000000000000
          id: 05b46288-37d4-4860-9de4-1edc6e8d5363
          mac: f8c1165aba00
          op: disable_port
          org_id: 174260d5-cb22-4ea8-badb-c77a89acb0a9
          port_id: ge-0/0/2
          reason: rogue_dhcp_server_detected
          site_id: 437ac5f0-fc76-4a2b-87ab-d8d1e5c00405
          src: marvis
          timestamp: 1775028130.405962
          type: wired
          vlan_ids: []
        - admin_id: 6d617276-0000-0000-3157-000000000000
          id: b1a81ed4-a7a2-4945-b01d-f54afe6d5cc4
          mac: f8c1165aba00
          op: add_vlans_to_port
          org_id: 174260d5-cb22-4ea8-badb-c77a89acb0a9
          port_id: ge-0/0/12
          reason: missing_vlans
          site_id: 437ac5f0-fc76-4a2b-87ab-d8d1e5c00405
          src: marvis
          timestamp: 1774866716.15723
          type: wired
          vlan_ids:
          - 100
          - 200
        start: 1775118621
        total: 2
    CountExample:
      value:
        distinct: string
        end: 0
        limit: 0
        results:
        - count: 0
          property: string
        start: 0
        total: 0
    HTTP403Example:
      value:
        detail: You do not have permission to perform this action.
    HTTP400Example:
      value:
        detail: 'JSON parse error - Expecting value: line 5 column 8 (char 56)'
    HTTP429Example:
      value:
        detail: Too Many Request. The API Token used for the request reached the 5000 API Calls per hour threshold
    MarvisConfigFeedbackResponseExample:
      value:
        feedback_note: this port config is intended, do not change anymore
        feedback_type: invalid
    HTTP401Example:
      value:
        detail: Authentication credentials were not provided.
  parameters:
    start:
      description: Lower bound of the time range, as an epoch timestamp in seconds or a relative value such as `-1d` or `-1w`
      in: query
      name: start
      schema:
        type: string
    duration:
      description: Time range duration for the query, using relative units such as `10m`, `7d`, or `2w`
      in: query
      name: duration
      schema:
        default: 1d
        examples:
        - 10m
        type: string
    limit:
      description: Maximum number of results to return per page
      in: query
      name: limit
      schema:
        default: 100
        minimum: 0
        type: integer
    site_id:
      in: path
      name: site_id
      required: true
      schema:
        examples:
        - 000000ab-00ab-00ab-00ab-0000000000ab
        format: uuid
        type: string
    end:
      description: Upper bound of the time range, as an epoch timestamp in seconds or a relative value such as `-1d`, `-2h`, or `now`
      in: query
      name: end
      schema:
        type: string
  schemas:
    response_http429:
      additionalProperties: false
      description: Standard HTTP 429 rate limit error response
      properties:
        detail:
          description: Human-readable explanation of the rate limit error
          examples:
          - Too Many Request. The API Token used for the request reached the 5000 API Calls per hour threshold
          type: string
      type: object
    response_http401:
      additionalProperties: false
      description: Standard HTTP 401 authentication error response
      properties:
        detail:
          description: Human-readable explanation of the authentication error
          examples:
          - Authentication credentials were not provided.
          type: string
      type: object
    response_http403:
      additionalProperties: false
      description: Standard HTTP 403 permission error response
      properties:
        detail:
          description: Human-readable explanation of the permission error
          examples:
          - You do not have permission to perform this action.
          type: string
      type: object
    marvis_config_actions_search:
      additionalProperties: false
      description: Paginated list of Marvis config actions
      properties:
        end:
          description: Search window end timestamp, in epoch seconds
          type: integer
        limit:
          description: Maximum number of results requested
          type: integer
        results:
          description: List of Marvis config actions
          items:
            $ref: '#/components/schemas/marvis_config_action'
          type: array
        start:
          description: Search window start timestamp, in epoch seconds
          type: integer
        total:
          description: Total number of matching results
          type: integer
      type: object
    marvis_config_feedback_response:
      additionalProperties: false
      description: Response after submitting feedback on a Marvis config action
      properties:
        feedback_note:
          description: The note provided with the feedback
          type: string
        feedback_type:
          description: The feedback type that was submitted
          type: string
      type: object
    count_results:
      description: List of count result rows
      items:
        $ref: '#/components/schemas/count_result'
      type: array
      uniqueItems: true
    response_http400:
      additionalProperties: false
      description: Standard HTTP 400 bad request error response
      properties:
        detail:
          description: Human-readable explanation of the bad request error
          examples:
          - 'JSON parse error - Expecting value: line 5 column 8 (char 56)'
          type: string
      type: object
    marvis_config_action:
      additionalProperties: false
      description: A Marvis-injected config action record
      properties:
        admin_id:
          description: Admin UUID associated with the config action
          format: uuid
          type: string
        id:
          description: UUID of the config action
          format: uuid
          type: string
        mac:
          description: Device MAC address
          type: string
        op:
          description: Operation type (e.g. disable_port, enable_port, update_mtu, add_vlans_to_port)
          type: string
        org_id:
          description: Organization UUID
          format: uuid
          type: string
        port_id:
          description: Port identifier (e.g. ge-0/0/13)
          type: string
        reason:
          description: Reason for the config action (e.g. rogue_dhcp_server_detected)
          type: string
        site_id:
          description: Site UUID
          format: uuid
          type: string
        src:
          description: Source of the config action (e.g. marvis)
          type: string
        timestamp:
          description: Timestamp when the config action was recorded, in epoch seconds
          type: number
        type:
          description: Config type (e.g. wired)
          type: string
        vlan_ids:
          description: List of VLAN IDs involved in the config action
          items:
            type: integer
          type: array
      type: object
    count_result:
      additionalProperties:
        type: string
      description: Count result row with the matching distinct field values
      properties:
        count:
          description: Number of matching items for the distinct value or values in this result
          type: integer
      required:
      - count
      type: object
    response_count:
      additionalProperties: false
      description: Distinct count response for time-bounded search results
      properties:
        distinct:
          description: Field used to group the count results
          type: string
        end:
          description: Search window end timestamp for the count request, in epoch seconds
          type: integer
        limit:
          description: Maximum number of distinct count results requested
          type: integer
        results:
          $ref: '#/components/schemas/count_results'
          description: Count results grouped by the distinct field
        start:
          description: Search window start timestamp for the count request, in epoch seconds
          type: integer
        total:
          description: Number of distinct result buckets returned
          type: integer
      required:
      - distinct
      - end
      - limit
      - results
      - start
      - total
      type: object
    marvis_config_feedback:
      additionalProperties: false
      description: Feedback submission for a Marvis config action
      properties:
        note:
          description: Free-text note about the feedback
          type: string
        type:
          description: 'Feedback type. enum: `invalid`'
          enum:
          - invalid
          type: string
      type: object
    response_http404:
      additionalProperties: false
      description: Standard HTTP 404 not found error response
      properties:
        id:
          description: Missing resource identifier, when the API includes one
          type: string
      type: object
  securitySchemes:
    apiToken:
      description: "Preferred authentication method for automation and integrations. Send the API token in the HTTP `Authorization` header.\n\n**Format**:\n  `Authorization: Token {apitoken}`\n\n**Notes**:\n* An API token generated for a specific admin has the same privileges as that admin\n* An API token is automatically removed if it is not used for more than 90 days\n* SSO admins cannot generate admin API tokens. Use organization API tokens when scoped Org/Site privileges are needed."
      in: header
      name: Authorization
      type: apiKey
    csrfToken:
      description: 'Session-based authentication for browser or login/password flows. After a successful [Login](/#operations/login) request, Mist returns a `csrftoken` cookie. Send that value in the `X-CSRFToken` header on later API requests that use the login session.


        **Format**:

        ```

        X-CSRFToken: vwvBuq9qkqaKh7lu8tNc0gkvBfEaLAmx

        ```


        For automation, API Token authentication is preferred.'
      in: header
      name: X-CSRFToken
      type: apiKey