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 Orgs User MACs 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: 'NAC User MACs (Endpoints) provide a database of endpoints identified by their MAC addresses. They can be used assign each endpoint with various attributes, such as name, VLAN, role and client label. Once an endpoint is labeled, the label name can be used to create [NAC Tags]($h/Orgs%20NAC%20Tags/_overview) as match criteria.
[NAC Tags]($h/Orgs%20NAC%20Tags/_overview) can be used to create Tags regrouping one or multiple endpoint MAC addresses, but the use of the User MACs provides additional features:
* possibility to assign specific attributes, like a Name, a RADIUS Group, a VLAN ID, ...
* possibility to assign one or multiple Tags (Labels) to a User MAC
* improved management for large list of MAC addresses'
name: Orgs User MACs
paths:
/api/v1/orgs/{org_id}/usermacs:
parameters:
- $ref: '#/components/parameters/org_id'
post:
description: "Create Org User MACs\n\n### Usermacs import CSV file format\nmac,labels,vlan,notes \n921b638445cd,\"bldg1,flor1\",vlan-100 \n721b638445ef,\"bldg2,flor2\",vlan-101,Canon Printers \n721b638445ee,\"bldg3,flor3\",vlan-102 \n921b638445ce,\"bldg4,flor4\",vlan-103 \n921b638445cf,\"bldg5,flor5\",vlan-104"
operationId: createOrgUserMac
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/user_mac'
responses:
'200':
$ref: '#/components/responses/UserMac'
'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: createOrgUserMac
tags:
- Orgs User MACs
put:
description: Update Multiple Org User MACs. Accepts a JSON array of user MAC objects where `id` is required for each entry.
operationId: updateOrgMultipleUserMacs
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/user_macs'
responses:
'200':
$ref: '#/components/responses/UserMacsUpdate'
'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: updateOrgMultipleUserMacs
tags:
- Orgs User MACs
/api/v1/orgs/{org_id}/usermacs/count:
parameters:
- $ref: '#/components/parameters/org_id'
get:
description: Count by Distinct Attributes of User MACs
operationId: countOrgUserMacs
parameters:
- description: 'Attribute to count by. enum: `mac`, `name`, `labels`, `org_id`'
in: query
name: distinct
required: true
schema:
$ref: '#/components/schemas/count_usermac_distinct'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
responses:
'200':
$ref: '#/components/responses/UserMacsCount'
'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: countOrgUserMacs
tags:
- Orgs User MACs
/api/v1/orgs/{org_id}/usermacs/delete:
parameters:
- $ref: '#/components/parameters/org_id'
post:
description: Delete Multiple Org User MACs
operationId: deleteOrgMultipleUserMacs
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/usermacs_id'
description: Request Body
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: deleteOrgMultipleUserMacs
tags:
- Orgs User MACs
/api/v1/orgs/{org_id}/usermacs/import:
parameters:
- $ref: '#/components/parameters/org_id'
post:
description: "Import Org User MACs. Accepts JSON or CSV upload.\n\n**JSON — Array form** (asynchronous by default):\n```json\n[\n {\"mac\": \"921b638445cd\", \"labels\": [\"label1\"], \"vlan\": \"vlan-1\"},\n {\"mac\": \"721b638445ef\", \"labels\": [\"label2\", \"label3\"], \"notes\": \"mac address refers to Canon printers\"}\n]\n```\n\n**CSV upload**: multipart/form-data with `file` field.\n\n### CSV file format\n```csv\nmac,labels,vlan,notes,name,radius_group\n921b638445cd,\"bldg1,flor1\",vlan-100\n721b638445ef,\"bldg2,flor2\",vlan-101,Canon Printers\n721b638445ee,\"bldg3,flor3\",vlan-102,Printer2,VIP\n921b638445ce,\"bldg4,flor4\",vlan-103\n921b638445cf,\"bldg5,flor5\",vlan-104\n```"
operationId: importOrgUserMacs
requestBody:
content:
application/json:
examples:
ArrayForm:
value:
- labels:
- label1
mac: 921b638445cd
vlan: vlan-1
- labels:
- label2
- label3
mac: 721b638445ef
notes: mac address refers to Canon printers
- labels:
- label4
mac: 721b638445ee
- labels:
- label5
- label6
- label7
mac: 921b638445ce
- mac: 921b638445cf
vlan: vlan-100
schema:
$ref: '#/components/schemas/user_macs'
multipart/form-data:
schema:
properties:
file:
description: CSV file containing user MAC entries to import
format: binary
type: string
required:
- file
type: object
responses:
'200':
$ref: '#/components/responses/UserMacImport'
'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: importOrgUserMacs
tags:
- Orgs User MACs
/api/v1/orgs/{org_id}/usermacs/search:
parameters:
- $ref: '#/components/parameters/org_id'
get:
description: Search Org User MACs
operationId: searchOrgUserMacs
parameters:
- $ref: '#/components/parameters/partial_filter_mac_usermac'
- description: Optional, array of strings of labels
in: query
name: labels
schema:
$ref: '#/components/schemas/search_org_user_macs_labels'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/sort'
responses:
'200':
$ref: '#/components/responses/UserMacsArray'
'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: searchOrgUserMacs
tags:
- Orgs User MACs
/api/v1/orgs/{org_id}/usermacs/{usermac_id}:
parameters:
- $ref: '#/components/parameters/org_id'
- $ref: '#/components/parameters/usermac_id'
delete:
description: Delete Org User MAC
operationId: deleteOrgUserMac
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: deleteOrgUserMac
tags:
- Orgs User MACs
get:
description: Get Org User MAC
operationId: getOrgUserMac
responses:
'200':
$ref: '#/components/responses/UserMac'
'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: getOrgUserMac
tags:
- Orgs User MACs
put:
description: Update Org User MAC
operationId: updateOrgUserMac
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/user_mac'
responses:
'200':
$ref: '#/components/responses/UserMac'
'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: updateOrgUserMac
tags:
- Orgs User MACs
components:
schemas:
uuids:
description: UUID string values used as identifiers
items:
format: uuid
type: string
type: array
user_macs:
description: List of user MAC entries
items:
$ref: '#/components/schemas/user_mac'
type: array
user_mac_labels:
description: Labels applied to a user MAC entry
examples:
- - byod
- flr1
items:
type: string
type: array
count_usermac_distinct:
description: 'Fields that can be used to group user MAC count results. enum: `mac`, `name`, `labels`, `org_id`'
enum:
- mac
- name
- labels
- org_id
examples:
- org_id
type: string
user_macs_update:
additionalProperties: false
description: Result of a bulk user MAC update
properties:
detail:
description: Status message returned for asynchronous batch updates
type: string
errors:
$ref: '#/components/schemas/strings'
description: Update errors reported for user MAC entries
updated:
$ref: '#/components/schemas/uuids'
description: User MAC entry IDs updated by the request
type: object
user_macs_count:
additionalProperties: false
description: User MACs count response
properties:
end:
description: Query end timestamp for user MAC counts
type: integer
limit:
description: Maximum number of distinct count results to return
type: integer
results:
description: User MAC entries returned by the count query
items:
$ref: '#/components/schemas/user_mac'
type: array
start:
description: Query start timestamp for user MAC counts
type: integer
total:
description: Overall number of user MAC count results
type: integer
type: object
id:
description: Unique ID of the object instance in the Mist Organization
examples:
- 53f10664-3ce8-4c27-b382-0ef66432349f
format: uuid
readOnly: true
type: string
strings:
description: Unique string values returned or accepted by this schema
items:
type: string
type: array
uniqueItems: true
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
search_org_user_macs_labels:
description: Labels associated with org user MAC search results
items:
type: string
type: array
user_mac_import_updated:
description: MAC addresses updated during a user MAC import
examples:
- - 721b638445ef
- 721b638445ee
items:
type: string
type: array
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
usermacs_id:
description: Request body for deleting multiple user MAC entries
properties:
usermac_ids:
$ref: '#/components/schemas/uuids'
description: User MAC entry IDs to delete
type: object
user_mac:
description: Organization user MAC entry
properties:
id:
$ref: '#/components/schemas/id'
description: Unique identifier for this user MAC entry
labels:
$ref: '#/components/schemas/user_mac_labels'
description: Applied labels for this user MAC entry
mac:
description: Client MAC address for this entry. Only non-local-admin MAC addresses are accepted
examples:
- 5684dae9ac8b
type: string
name:
description: Display name for this user MAC entry
examples:
- Printer2
type: string
notes:
description: Free-form notes about this user MAC entry
examples:
- MAC address refers to Canon printers
type: string
radius_group:
description: RADIUS group associated with this user MAC entry
examples:
- VIP
type: string
vlan:
description: Network VLAN value associated with this user MAC entry
examples:
- '30'
type: string
required:
- mac
type: object
user_mac_import_errors:
description: Error messages returned during a user MAC import
examples:
- - 921b638445ce - mac invalid
- 921b638445cf - mac already provided
items:
type: string
type: array
user_mac_import:
additionalProperties: false
description: Result of importing user MAC entries
properties:
added:
$ref: '#/components/schemas/user_mac_import_added'
description: MAC addresses added by the import
detail:
description: Status message returned for asynchronous imports
type: string
errors:
$ref: '#/components/schemas/user_mac_import_errors'
description: Import error messages for user MAC entries
updated:
$ref: '#/components/schemas/user_mac_import_updated'
description: MAC addresses updated by the import
type: object
user_mac_import_added:
description: MAC addresses added during a user MAC import
examples:
- - 921b638445cd
items:
type: string
type: array
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
examples:
UserMacExample:
value:
id: 111cafd2-ba1b-5169-bfcb-9cdf1d473ddb
labels:
- flor1
- bld4
mac: 921b638445cd
notes: MAC address refers to Canon printers
vlan: '30'
UserMacImportAsyncExample:
value:
detail: import in progress
HTTP403Example:
value:
detail: You do not have permission to perform this action.
UserMacsUpdateExample:
value:
errors:
- 2feacc8e-5893-418a-acaa-4d7c1afd01fe - invalid id
updated:
- 1041c16c-ca87-4d3f-bb94-b97c5819fc09
- a016cc8e-5893-418a-acaa-4d7c1af6ac0f
HTTP400Example:
value:
detail: 'JSON parse error - Expecting value: line 5 column 8 (char 56)'
UserMacsArrayExample:
value:
- id: 111cafd2-ba1b-5169-bfcb-9cdf1d473ddb
labels:
- flor1
- bld4
mac: 921b638445cd
notes: MAC address refers to Canon printers
vlan: '30'
HTTP429Example:
value:
detail: Too Many Request. The API Token used for the request reached the 5000 API Calls per hour threshold
UserMacImportExample:
value:
added:
- 921b638445cd
errors:
- 921b638445ce - mac invalid
- 921b638445cf - mac already provided
updated:
- 721b638445ef
- 721b638445ee
UserMacsUpdateAsyncExample:
value:
detail: batch update in progress
HTTP401Example:
value:
detail: Authentication credentials were not provided.
parameters:
org_id:
in: path
name: org_id
required: true
schema:
examples:
- 000000ab-00ab-00ab-00ab-0000000000ab
format: uuid
type: string
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
sort:
description: On which field the list should be sorted, -prefix represents DESC order
in: query
name: sort
schema:
default: timestamp
examples:
- -site_id
type: string
usermac_id:
in: path
name: usermac_id
required: true
schema:
examples:
- 000000ab-00ab-00ab-00ab-0000000000ab
format: uuid
type: string
limit:
description: Maximum number of results to return per page
in: query
name: limit
schema:
default: 100
minimum: 0
type: integer
page:
description: Select the page number to return when using page-based pagination; starts at `1`
in: query
name: page
schema:
default: 1
minimum: 1
type: integer
partial_filter_mac_usermac:
description: Partial / full Client MAC address. Use `prefix*` for prefix search or `*substring*` for contains search (e.g. `aabbcc*` and `*bbcc*` match `aabbccddeeff`). Suffix-only wildcards (e.g. `*bccddeeff`) are not supported
in: query
name: mac
schema:
examples:
- aabbccddeeff
- aabbcc*
- '*bbcc*'
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
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
UserMac:
content:
application/json:
examples:
Example:
$ref: '#/components/examples/UserMacExample'
schema:
$ref: '#/components/schemas/user_mac'
application/vnd.api+json:
examples:
Example:
$ref: '#/components/examples/UserMacExample'
schema:
$ref: '#/components/schemas/user_mac'
description: OK
UserMacsArray:
content:
application/json:
examples:
Example:
$ref: '#/components/examples/UserMacsArrayExample'
schema:
$ref: '#/components/schemas/user_macs'
application/vnd.api+json:
examples:
Example:
$ref: '#/components/examples/UserMacsArrayExample'
schema:
$ref: '#/components/schemas/user_macs'
description: OK
UserMacsUpdate:
content:
application/json:
examples:
Async:
$ref: '#/components/examples/UserMacsUpdateAsyncExample'
Sync:
$ref: '#/components/examples/UserMacsUpdateExample'
schema:
$ref: '#/components/schemas/user_macs_update'
application/vnd.api+json:
examples:
Async:
$ref: '#/components/examples/UserMacsUpdateAsyncExample'
Sync:
$ref: '#/components/examples/UserMacsUpdateExample'
schema:
$ref: '#/components/schemas/user_macs_update'
description: OK
UserMacImport:
content:
application/json:
examples:
Async:
$ref: '#/components/examples/UserMacImportAsyncExample'
Sync:
$ref: '#/components/examples/UserMacImportExample'
schema:
$ref: '#/components/schemas/user_mac_import'
application/vnd.api+json:
examples:
Async:
$ref: '#/components/examples/UserMacImportAsyncExample'
Sync:
$ref: '#/components/examples/UserMacImportExample'
schema:
$ref: '#/components/schemas/user_mac_import'
description: OK
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
UserMacsCount:
content:
application/json:
schema:
$ref: '#/components/schemas/user_macs_count'
application/vnd.api+json:
schema:
$ref: '#/components/schemas/user_macs_count'
description: OK
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
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