A Service represents an a traffic destination or an application that network users connect to. They are associated with users and networks and are used in application policies to permit or deny access. Services are defined at the [Org level](/#operations/createOrgService). The Site level endpoints can be used to get the site services statistics or the derived services, meaning the merge between the site level configuration and the org level configuration.
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 Services 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: 'A Service represents an a traffic destination or an application that network users connect to. They are associated with users and networks and are used in application policies to permit or deny access.
Services are defined at the [Org level](/#operations/createOrgService).
The Site level endpoints can be used to get the site services statistics or the derived services, meaning the merge between the site level configuration and the org level configuration.'
name: Sites Services
paths:
/api/v1/sites/{site_id}/services/derived:
parameters:
- $ref: '#/components/parameters/site_id'
get:
description: Get the list of derived Services for a Site
operationId: listSiteServicesDerived
parameters:
- description: Whether resolve the site variables
in: query
name: resolve
schema:
default: false
type: boolean
responses:
'200':
$ref: '#/components/responses/ServicesArray'
'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: listSiteServicesDerived
tags:
- Sites Services
/api/v1/sites/{site_id}/services/events/count:
parameters:
- $ref: '#/components/parameters/site_id'
get:
description: Count by Distinct Attributes of Service Path Events
operationId: countSiteServicePathEvents
parameters:
- description: 'Field used to group this count response. enum: `mac`, `model`, `policy`, `port_id`, `site_id`, `type`, `vpn_name`, `vpn_path`'
in: query
name: distinct
schema:
$ref: '#/components/schemas/site_service_events_count_distinct'
- description: Event type, e.g. GW_SERVICE_PATH_DOWN
in: query
name: type
schema:
type: string
- description: Description of the event including the reason it is triggered
in: query
name: text
schema:
type: string
- description: Filter results by vpn name
in: query
name: vpn_name
schema:
type: string
- description: Filter results by vpn path
in: query
name: vpn_path
schema:
type: string
- description: Service policy associated with that specific path
in: query
name: policy
schema:
type: string
- description: Filter results by port identifier
in: query
name: port_id
schema:
type: string
- description: Filter results by device model
in: query
name: model
schema:
type: string
- description: Filter results by software version
in: query
name: version
schema:
type: string
- description: Filter results by MAC address
in: query
name: mac
schema:
type: string
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
- $ref: '#/components/parameters/duration'
- $ref: '#/components/parameters/limit'
responses:
'200':
$ref: '#/components/responses/Count'
'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: countSiteServicePathEvents
tags:
- Sites Services
/api/v1/sites/{site_id}/services/events/search:
parameters:
- $ref: '#/components/parameters/site_id'
get:
description: Search Service Path Events
operationId: searchSiteServicePathEvents
parameters:
- description: Event type, e.g. GW_SERVICE_PATH_DOWN
in: query
name: type
schema:
type: string
- description: Description of the event including the reason it is triggered
in: query
name: text
schema:
type: string
- description: Port ID of the peer gateway
in: query
name: peer_port_id
schema:
type: string
- description: MAC address of the peer gateway
in: query
name: peer_mac
schema:
type: string
- description: Filter results by vpn name
in: query
name: vpn_name
schema:
type: string
- description: Filter results by vpn path
in: query
name: vpn_path
schema:
type: string
- description: Service policy associated with that specific path
in: query
name: policy
schema:
type: string
- description: Filter results by port identifier
in: query
name: port_id
schema:
type: string
- description: Filter results by device model
in: query
name: model
schema:
type: string
- description: Filter results by software version
in: query
name: version
schema:
type: string
- description: Filter results by MAC address
in: query
name: mac
schema:
type: string
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
- $ref: '#/components/parameters/duration'
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/search_after'
responses:
'200':
$ref: '#/components/responses/ServicePathEventsSearch'
'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: searchSiteServicePathEvents
tags:
- Sites Services
components:
schemas:
service_apps:
description: "When `type`==`apps`, list of applications are available through:\n * [List Applications](/#operations/listApplications)\n * [List Gateway Applications](/#operations/listGatewayApplications)\n * /insight/top_app_by-bytes?wired=true"
examples:
- - office365
- okta
items:
type: string
type: array
services:
description: Service definitions returned by list operations
items:
$ref: '#/components/schemas/service'
type: array
service_dscp:
description: For SSR only, when `traffic_type`==`custom`. 0-63 or variable
oneOf:
- type: string
- maximum: 63
minimum: 0
type: integer
response_events_path_search_results:
description: Service path event records returned by a search response
items:
$ref: '#/components/schemas/service_path_event'
type: array
timestamp:
description: Epoch timestamp, in seconds
format: double
readOnly: true
type: number
service_specs:
description: When `type`==`custom`, optional, if it doesn't exist, http and https is assumed
items:
$ref: '#/components/schemas/service_spec'
type: array
service_traffic_class:
default: best_effort
description: 'when `traffic_type`==`custom`. enum: `best_effort`, `high`, `low`, `medium`'
enum:
- best_effort
- high
- low
- medium
type: string
id:
description: Unique ID of the object instance in the Mist Organization
examples:
- 53f10664-3ce8-4c27-b382-0ef66432349f
format: uuid
readOnly: true
type: string
org_id:
description: Unique identifier of a Mist organization
examples:
- a97c1b22-a4e9-411e-9bfd-d8695a0f9e61
format: uuid
readOnly: true
type: string
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_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
created_time:
description: When the object has been created, in epoch
format: double
readOnly: true
type: number
service_max_loss:
description: For SSR only, when `traffic_type`==`custom`, for uplink selection. 0-100 or variable
oneOf:
- type: string
- maximum: 100
minimum: 0
type: integer
service_failover_policy:
default: revertible
description: 'enum: `non_revertible`, `none`, `revertible`'
enum:
- non_revertible
- none
- revertible
type: string
service_hostnames:
description: If `type`==`custom`, web filtering
items:
examples:
- example.com
type: string
type: array
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
service_app_categories:
description: When `type`==`app_categories`, list of application categories are available through [List App Category Definitions](/#operations/listAppCategoryDefinitions)
examples:
- - Sports
items:
type: string
type: array
site_service_events_count_distinct:
default: type
description: 'enum: `mac`, `model`, `policy`, `port_id`, `site_id`, `type`, `vpn_name`, `vpn_path`'
enum:
- mac
- model
- policy
- port_id
- site_id
- type
- vpn_name
- vpn_path
type: string
service_path_event:
additionalProperties: false
description: Event describing a service path state change reported by a gateway or SSR device
properties:
mac:
description: Device MAC address that reported the service path event
examples:
- 90ec7734b374
type: string
model:
description: Device model that reported the service path event
examples:
- SSR120
type: string
org_id:
$ref: '#/components/schemas/org_id'
description: Organization identifier associated with the service path event
policy:
description: Service policy name associated with the path event
examples:
- INTERNET
type: string
port_id:
description: Network interface associated with the service path event
examples:
- ge-1/0/6
type: string
site_id:
$ref: '#/components/schemas/site_id'
description: Site identifier associated with the service path event
text:
description: Human-readable message for the service path event
examples:
- Peer Path Down
type: string
timestamp:
$ref: '#/components/schemas/timestamp'
description: Time when the service path event occurred, in epoch seconds
type:
description: Event type for the service path change
examples:
- GW_SERVICE_PATH_REMOVE
type: string
version:
description: Device firmware version that reported the service path event
examples:
- 6.1.5-14.lts
type: string
vpn_name:
description: Peer name associated with the service path event
examples:
- Syracuse_HUB
type: string
vpn_path:
description: Peer path name associated with the service path event
examples:
- Syracuse_HUB-Wan0
type: string
type: object
count_results:
description: List of count result rows
items:
$ref: '#/components/schemas/count_result'
type: array
uniqueItems: true
service_urls:
description: When `type`==`urls`, no need for spec as URL can encode the ports being used
items:
type: string
type: array
service_app_subcategories:
description: When `type`==`app_categories`, list of application categories are available through [List App Sub Category Definitions](/#operations/listAppSubCategoryDefinitions)
examples:
- - Shopping
items:
type: string
type: array
service:
description: Traffic service definition for applications or destinations used by gateway and SSR policies
properties:
addresses:
$ref: '#/components/schemas/service_addresses'
description: Custom IPv4 or IPv6 subnets matched by this service when `type`==`custom`
app_categories:
$ref: '#/components/schemas/service_app_categories'
description: Categories of applications matched by this service when `type`==`app_categories`
app_subcategories:
$ref: '#/components/schemas/service_app_subcategories'
description: Application subcategories matched by this service when `type`==`app_categories`
apps:
$ref: '#/components/schemas/service_apps'
description: Application identifiers matched by this service when `type`==`apps`
client_limit_down:
default: 0
description: 0 means unlimited, value from 0 to 107374182
examples:
- 300000
maximum: 107374182
minimum: 0
type: integer
client_limit_up:
default: 0
description: 0 means unlimited, value from 0 to 107374182
examples:
- 300000
maximum: 107374182
minimum: 0
type: integer
created_time:
$ref: '#/components/schemas/created_time'
description: Timestamp when the service definition was created, in epoch seconds
description:
description: Free-form description of the service definition
type: string
dscp:
$ref: '#/components/schemas/service_dscp'
description: QoS DSCP value used for custom SSR traffic classification
failover_policy:
$ref: '#/components/schemas/service_failover_policy'
description: Failover behavior for traffic matched by this service
hostnames:
$ref: '#/components/schemas/service_hostnames'
description: Domain hostnames matched by this custom service for web filtering
id:
$ref: '#/components/schemas/id'
description: Unique value identifying the service definition
max_jitter:
$ref: '#/components/schemas/service_max_jitter'
description: Maximum jitter threshold used for SSR uplink selection when `traffic_type`==`custom`
max_latency:
$ref: '#/components/schemas/service_max_latency'
description: Maximum latency threshold used for SSR uplink selection when `traffic_type`==`custom`
max_loss:
$ref: '#/components/schemas/service_max_loss'
description: Maximum packet loss threshold used for SSR uplink selection when `traffic_type`==`custom`
modified_time:
$ref: '#/components/schemas/modified_time'
description: Timestamp when the service definition was last modified, in epoch seconds
name:
description: Display name of the service definition
type: string
org_id:
$ref: '#/components/schemas/org_id'
description: Organization identifier associated with the service definition
service_limit_down:
default: 0
description: 0 means unlimited, value from 0 to 107374182
examples:
- 300000
maximum: 107374182
minimum: 0
type: integer
service_limit_up:
default: 0
description: 0 means unlimited, value from 0 to 107374182
examples:
- 300000
maximum: 107374182
minimum: 0
type: integer
sle_enabled:
default: false
description: Whether to enable measure SLE
type: boolean
specs:
$ref: '#/components/schemas/service_specs'
description: Protocol and port match rules used when `type`==`custom`
ssr_relaxed_tcp_state_enforcement:
default: false
description: Whether SSR relaxes TCP state enforcement for this service
type: boolean
traffic_class:
$ref: '#/components/schemas/service_traffic_class'
description: Traffic class applied when `traffic_type`==`custom`
traffic_type:
default: data_best_effort
description: values from [List Traffic Types](/#operations/listTrafficTypes)
type: string
type:
$ref: '#/components/schemas/service_type'
description: Matching mode that determines which app, URL, or custom fields are used
urls:
$ref: '#/components/schemas/service_urls'
description: URL patterns matched by this service when `type`==`urls`
type: object
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
service_max_latency:
description: For SSR only, when `traffic_type`==`custom`, for uplink selection. 0-2147483647 or variable
oneOf:
- type: string
- maximum: 2147483647
minimum: 0
type: integer
service_addresses:
description: If `type`==`custom`, IPv4 and/or IPv6 subnets (e.g. 10.0.0.0/8, fd28::/128)
examples:
- - 10.0.0.0/8
- 172.21.0.0/16
- 2001:db8:abcd:12::/64
- fd28::/128
items:
type: string
type: array
response_events_path_search:
additionalProperties: false
description: Paginated response for service path event search results
properties:
end:
description: Epoch timestamp for the end of the service path event search window
examples:
- 1697096379
type: integer
limit:
description: Maximum number of service path event records returned in this page
examples:
- 10
type: integer
next:
description: Pagination cursor or URL for retrieving the next page of service path event records
type: string
results:
$ref: '#/components/schemas/response_events_path_search_results'
description: Service path event records matching the search filters
start:
description: Epoch timestamp for the start of the service path event search window
examples:
- 1697009979
type: integer
total:
description: Number of service path event records matching the search filters across all pages
examples:
- 2
type: integer
type: object
service_spec:
additionalProperties: false
description: Protocol and port match rule for a custom service
properties:
port_range:
description: Port number, port range, or variable
examples:
- 8080,8443
type: string
protocol:
default: any
description: '`https`/ `tcp` / `udp` / `icmp` / `gre` / `any` / `:protocol_number`, `protocol_number` is between 1-254'
examples:
- tcp
type: string
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
service_type:
default: custom
description: 'enum: `app_categories`, `apps`, `custom`, `urls`'
enum:
- app_categories
- apps
- custom
- urls
type: string
site_id:
description: Unique identifier of a Mist site
examples:
- 441a1214-6928-442a-8e92-e1d34b8ec6a6
format: uuid
readOnly: true
type: string
modified_time:
description: When the object has been modified for the last time, in epoch
format: double
readOnly: true
type: number
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
service_max_jitter:
description: For SSR only, when `traffic_type`==`custom`, for uplink selection. 0-2147483647 or variable
oneOf:
- type: string
- maximum: 2147483647
minimum: 0
type: integer
responses:
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
Count:
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: Result of Count
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
ServicesArray:
content:
application/json:
examples:
Example:
$ref: '#/components/examples/ServicesArrayExample'
schema:
$ref: '#/components/schemas/services'
application/vnd.api+json:
examples:
Example:
$ref: '#/components/examples/ServicesArrayExample'
schema:
$ref: '#/components/schemas/services'
description: OK
ServicePathEventsSearch:
content:
application/json:
examples:
Example:
$ref: '#/components/examples/ServicePathEventsSearchExample'
schema:
$ref: '#/components/schemas/response_events_path_search'
application/vnd.api+json:
examples:
Example:
$ref: '#/components/examples/ServicePathEventsSearchExample'
schema:
$ref: '#/components/schemas/response_events_path_search'
description: Example response
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
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
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
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
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
search_after:
description: Pagination cursor for retrieving subsequent pages of results. This value is automatically populated by Mist in the `next` URL from the previous response and should not be manually constructed.
in: query
name: search_after
schema:
type: string
examples:
CountExample:
value:
distinct: string
end: 0
limit: 0
results:
- count: 0
property: string
start: 0
total: 0
ServicePathEventsSearchExample:
value:
end: 1697096379
limit: 10
results:
- mac: 90ec7734b374
model: SSR120
org_id: a3c6718f-2823-4e48-bf5e-b841768a4c9b
policy: INTERNET
port_id: ge-1/0/6
site_id: 4279edbd-1d24-41ea-9505-2eb26c8590fa
text: Peer Path Down
timestamp: 1697037328.651775
type: GW_SERVICE_PATH_REMOVE
version: 6.1.5-14.lts
vpn_name: Syracuse_HUB
vpn_path: Syracuse_HUB-Wan0
start: 1697009979
total: 2
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
ServicesArrayExample:
value:
- addresses:
- string
apps:
- string
dscp: 8
hostnames:
- string
max_jitter: 0
max_latency: 0
max_loss: 0
name: string
specs:
- port_range: '0'
protocol: any
traffic_class: best_effort
traffic_type: default
type: custom
HTTP401Example:
value:
detail: Authentication credentials were not provided.
securitySch
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mist/refs/heads/main/openapi/mist-sites-services-api-openapi.yml