Splunk Observability Cloud Navigators
API for creating, updating, retrieving, and deleting custom navigators.
OpenAPI Specification
openapi: 3.0.3
info:
title: Splunk Observability Cloud — Navigators
version: 3.0.1
description: 'API for creating, updating, retrieving, and deleting custom navigators.
Requirements
You must have an organization access token with the API permission or a session token to use the API.
You have to have the Splunk Observability Cloud admin role to use the POST /navigator, PUT /navigator/{id}, DELETE /navigator/{id},
POST /navigator/{id}/navigatorcustomization, PUT /navigator/{id}/navigatorcustomization/{customizationId}, and DELETE
/navigator/{id}/navigatorcustomization/{customizationId} operations.
You have to have the Splunk Observability Cloud admin, power, or read_only role to use the GET /navigator, GET /navigator/{id},
GET /navigator/{id}/dashboards, GET /navigator/{id}/navigatorcustomization, and GET /navigator/{id}/navigatorcustomization/{customizationId}
operations.'
x-provenance:
method: reconstructed
authored_by: Splunk (content) / API Evangelist (assembly)
reconstructed_by: API Evangelist
reconstructed_on: '2026-08-19'
first_party: false
provider_published: false
note: Splunk's own OpenAPI objects, extracted from the React Server Component payload embedded in each of the 48 API reference
pages at dev.splunk.com. The operations and schemas are Splunk's; the assembly into standalone documents is API Evangelist's.
Splunk serves no fetchable spec file — dev.splunk.com answers 200 with an identical 6,638-byte shell for every asset
path, including invented control paths — so this is NOT first-party publication and is not graded as such.
x-evidence:
- type: source
url: https://dev.splunk.com/observability/reference/
- type: source
url: https://dev.splunk.com/observability/docs/apibasics/api_list/
servers:
- url: https://api.{REALM}.observability.splunkcloud.com/v2
description: Base API endpoint URL for custom navigator
variables:
REALM:
default: us0
description: Splunk Observability Cloud realm the organization is provisioned in (for example us0, us1, eu0, jp0, au0).
security:
- SessionToken: []
components:
securitySchemes:
SessionToken:
type: apiKey
in: header
name: X-SF-Token
description: Splunk Observability Cloud session token or org access token.
paths:
/navigator:
get:
summary: Retrieve Navigators Query
description: 'Retrieves the properties of one or more navigators. If you don''t specify any query parameters, the API
returns up to the first 200 navigator objects that you have access to.
Note: Splunk Observability Cloud returns a maximum of 10,000 navigators, even if your organization contains more than
10,000 navigators. To learn more, see the Considerations for retrieve operations section in the developer guide.'
parameters:
- name: limit
in: query
description: Number of navigators to retrieve from the list of navigators that match your search criteria.
schema:
type: integer
format: int32
default: 200
example: 100
- name: displayName
in: query
description: 'Search string that the system compares to existing navigator names. A match occurs if the string matches
any part of the navigator name. For example, the query specification displayName="per" matches the following (ellipses
represent other parts of the name):
"...dropped per day..."
"...95th percentile"
"personal disk usage..."
The string can contain only ASCII characters.'
schema:
type: string
- name: offset
in: query
description: 0-based index of the point in the query results where the system starts returning navigators. If the
offset value is greater than the size of the result set, you don't receive any results.
schema:
type: integer
format: int32
- name: Accept
in: header
description: Format of the response body. Always "application/vnd.splunk.observability.navigator+json".
required: true
schema:
type: string
- name: X-SF-TOKEN
in: header
description: Authentication token
required: true
schema:
type: string
responses:
'200':
description: HTTP 200 response
content:
application/vnd.splunk.observability.navigator+json:
schema:
title: Valid Get Navigators Response
type: object
properties:
count:
type: integer
format: int32
description: 'Number of navigators that matched the provided search criteria.
Note: This value is the total number of matches, not the number of navigators returned. The number of
navigators that the system returns is affected by the limit and offset query parameters.
In summary:
sizeOf(results): Number of navigators returned in the response body.
count: Number of navigators that match the search criteria.'
results:
type: array
items:
type: object
properties:
aggregateDashboards:
title: Dashboard ID array for aggregate display
type: array
maxItems: 10
items:
type: string
example:
- DiVWXF8AgAA
- DiVV1eUAgAA
- DiVWbW3AgAA
description: List of dashboard IDs you want to show in the aggregate view of this navigator. Aggregate
view is the view when you first open a navigator. In the aggregate view, you can see all instances
of the integration represented by this navigator, in the form of a heatmap or a table.
alertQuery:
title: Navigator alert query
type: string
example: _exists_:AWSUniqueId AND (namespace:"AWS/EC2" OR cloud.platform:aws_ec2)
description: Query that retrieves alerts associated with this navigator.
categories:
title: Navigator categories list
type: array
maxItems: 1
items:
title: Navigator category
type: object
required:
- categoryName
properties:
categoryName:
title: Category display name
type: string
maxLength: 50
example: Amazon Web Services
description: 'Display name for the category.
Note: If this parameter is empty, the display name is "Other".'
categoryGroupName:
title: Category group name
type: string
maxLength: 50
example: Public Clouds
description: 'Name of the group where this category belongs.
Note: If this parameter is empty, the display name is "Other".'
categoryInstanceLabel:
title: Category instance label
type: string
maxLength: 50
example: service
description: General name for each navigator in this category.
description: Details about a category for this navigator.
description: 'List of categories where this navigator belongs, in the form of a JSON array. Each
element is a single category.
Note: If you specify a category object with the same categoryName as the categoryName of an existing
category object, the navigator is put into the existing category object and all other fields of
the new category object are ignored.'
created:
title: Date and time when this navigator was created
type: integer
format: int64
readOnly: true
example: 1550097801307
description: Date and time the navigator was created, in the form of a *nix timestamp in milliseconds.
This property is read-only and is generated by the system.
creator:
title: Navigator creator user ID
type: string
readOnly: true
example: AAAAAAAAAAA
description: User ID of the user who created this navigator. This property is read-only and is generated
by the system.
defaultGroupBy:
title: Navigator default group by
type: string
description: A property that indicates how you want to group the instances in the navigator by default.
If defaultGroupBy is set then by default, the instances are grouped by this property when you
view the navigator.
displayName:
title: Navigator display name
type: string
maxLength: 50
example: Elastic Load Balancers
description: A short name for the navigator that appears in the UI.
id:
title: Navigator system ID
type: string
readOnly: true
example: DzUCanSAEu8
description: Unique ID of a navigator. This property is read-only and is generated by the system.
idDisplayName:
title: Navigator ID display name
type: string
example: '{{aws_tag_Name}}'
description: 'This property value appears as the tooltip title when you hover over the navigator
in the UI.
Note: If idDisplayName is empty, the navigator ID appears instead.'
instanceDashboards:
title: Dashboard ID array for instance display
type: array
maxItems: 10
items:
type: string
example:
- DiVWWU5AYAA
- DiVWZODAgAA
description: List of dashboard IDs you want to show in the instance display of this navigator. Instance
view is the view you get when you select an individual instance of the integration from the heatmap
or table in the aggregate view of this navigator.
instanceDisplayText:
title: Instance display text
type: string
maxLength: 100
example: Elastic Load Balancer
description: Description for a single instance of this navigator. This description is used when
displaying the long name of a single instance in this navigator.
instanceLabel:
title: Navigator instance label
type: string
maxLength: 50
example: Load Balancer
description: Label for a single instance of this navigator in the UI.
lastUpdated:
title: Navigator last updated time
type: integer
format: int64
readOnly: true
example: 1550097801307
description: Date and time the navigator was last updated, in the form of a *nix timestamp in milliseconds.
This property is read-only and is generated by the system.
lastUpdatedBy:
title: User who last updated this navigator
type: string
readOnly: true
example: AAAAAAAAAAA
description: User ID of the user who last updated this navigator. This property is read-only and
is generated by the system.
listColumns:
title: Navigator column list
type: array
maxItems: 10
items:
title: List column items
type: object
required:
- displayName
- property
properties:
displayName:
title: Column display name
type: string
maxLength: 100
example: Availability Zone
description: Column display name
format:
title: Column format
type: string
enum:
- id
- Number
- Kilobytes
- Bytes
- Seconds
- Age
- Percentage
- ScaleBytes
- ScaleKilobytes
- Boolean
- AlertSeverity
- aws_state
example: Number
description: 'Format of the values in this column.
Note: If format is empty, the format defaults to string.'
property:
title: Property to display in this column
type: string
maxLength: 100
example: AvailabilityZone
description: Name of the dimension or custom property to display in this column
description: A single column you want to see in the table view of this navigator.
description: List of columns you want to see in the table view of this navigator, in the form of
a JSON array. Each element is a single column.
navigatorCode:
title: Navigator unique code
type: string
example: elb
readOnly: true
description: Unique code used to identify a built-in navigator. This property appears in the navigator
URL.
ownerScope:
title: How the navigator was created
type: string
enum:
- splunk
- organization
readOnly: true
example: organization
description: 'Indicates how the navigator was created. These are the possible values:
splunk: Navigator is a built-in navigator.
organization: Navigator was created by a user using the API.
Note: You can only use organization when creating or updating navigators. If you try to pass an
invalid value for ownerScope when creating or updating detectors, you will receive a 403 response
and an error message saying "Cannot change or export built-in navigators in this org".'
propertyIdentifierTemplate:
title: Template for ID construction
type: string
example: '{{LoadBalancerName}} | {{AvailabilityZone}}'
description: A template used for constructing IDs for the instances in this navigator. Properties
inside the left braces and right braces ({{ }}) will be evaluated from the instance and populated
with the property value. For example, if you use load balancer name and availability zone to construct
an instance ID, an instance ID might look like i-00ddab733ad2a6d47_us-west-1.
entityMetrics:
title: Navigator metric information
type: array
maxItems: 30
items:
title: Metric to display on a navigator
type: object
required:
- id
- metricSelectors
- job
- type
properties:
coloringScheme:
title: Metric coloring scheme
type: object
properties:
minValue:
title: Minimum value
type: integer
format: int64
example: 0
description: 'Optional lower bound used for default coloring. Null value indicates that
there is no logical lower bound and the minimum value is set based on the range of the
dataset.
Note: If you specify minValue and maxValue, then maxValue must be greater than minValue.'
maxValue:
title: Maximum value
type: integer
format: int64
example: 50
description: 'Optional upper bound used for default coloring. Null value indicates that
there is no logical upper bound and the maximum value is set based on the range of the
dataset.
Note: If you specify minValue and maxValue, then maxValue must be greater than minValue.'
palette:
title: Coloring palette
type: string
enum:
- RED_GREEN
- GREEN_RED
- PURPLE_BLUE
- BLUE_PURPLE
- LEGACY
example: RED_GREEN
description: 'Color palette for the coloring scheme. These are gradient palettes that
flow from one color to the other, based on data points distribution. These are the possible
values:
RED_GREEN: The palette is a gradient from red to green, with lower values colored in
red and higher values colored in green.
GREEN_RED: The palette is a gradient from green to red, with lower values colored in
green and higher values colored in red.
PURPLE_BLUE: The palette is a gradient from purple to blue, with lower values colored
in purple and higher values colored in blue.
BLUE_PURPLE: The palette is a gradient from blue to purple, with lower values colored
in blue and higher values colored in purple.
LEGACY: Only available for navigators with ownerScope: splunk. You can''t use this value
when creating or updating a navigator with ownerScope: organization.'
thresholds:
title: Coloring thresholds
type: array
maxItems: 5
items:
title: Coloring threshold
properties:
lowerLimit:
title: Lower limit
type: integer
format: double
description: Lower limit of the threshold
paletteIndex:
title: Palette index
type: integer
format: int64
description: 0-based index that specifies which color in the gradient is assigned
to the range bounded at the lower limit by this threshold. Possible values are
0 to 4, inclusive.
description: Single coloring threshold
example:
- lowerLimit: 0
paletteIndex: 0
- lowerLimit: 10
paletteIndex: 1
- lowerLimit: 100
paletteIndex: 2
- lowerLimit: 1000
paletteIndex: 3
- lowerLimit: 10000
paletteIndex: 4
description: Optional list of thresholds to determine colors, in the form of a JSON array.
Each element is an individual coloring threshold.
description: 'How the heatmap or table nodes are colored for a particular metric. By default,
the navigator uses automatic coloring based on the dataset. The default coloring scheme
divides the dataset into five segments, defined by the range of colors.
If you provide a list of thresholds, then specific thresholds are used to determine coloring.
You can provide either minValue and maxValue, or a list of thresholds, but not both.'
description:
title: Metric description
type: string
maxLength: 300
example: 'Color hosts based on percentage of CPU being used: under 20% (green) to over 80%
(red)'
description: Explanation for the coloring scheme of the metric.
displayName:
title: Metric display name
type: string
maxLength: 100
example: CPU Utilization
description: Metric display name
job:
title: Metric job
type: object
required:
- resolution
- template
- varName
properties:
resolution:
title: Resolution of the job
type: integer
format: int64
example: 300000
description: Resolution of the job in milliseconds
template:
title: SignaFlow template
type: string
example: CPU_UTILIZATION = data("^aws.ec2.cpu.utilization"{{#filter}}, filter={{{filter}}}{{/filter}},
extrapolation="last_value", maxExtrapolations=2).mean(by=["AWSUniqueId"])
description: SignalFlow template that generates the heatmap or list of metrics for display
on a navigator
varName:
title: Variable name
type: string
example: CPU_UTILIZATION
description: Variable name used in the template
filters:
title: Filter list
type: array
items:
title: Filter for a metric job
type: object
required:
- property
properties:
property:
title: Property key to filter
type: string
example: _exists_
description: 'Name of the dimension or custom property to match to the data.
Note: If the dimension or custom property doesn''t exist in any of the entity
metrics for the navigator, and JobFilter.NOT is true, the system doesn''t display
any metric in the navigator.'
propertyValue:
title: Property values to filter
oneOf:
- type: string
- type: array
example: AWSUniqueId
description: Property values to filter
not:
title: Indicates of the property is included or excluded
type: boolean
default: false
example: false
description: Flag that indicates how the filter operates. If true, data that matches
the criteria is excluded from the filter; otherwise, data that matches the criteria
is included.
type:
title: Property type
type: string
example: property
description: Indicates if this is a custom property or a dimension
description: A single filter for a metric job. The filter specifies a default or user-defined
dimension or custom property. You can either include or exclude all the data that
matches this dimension or custom property.
description: List of filters for the job, in the form of a JSON array. Each element is
a single filter for a default or user-defined dimension or custom property.
description: Metric job
id:
title: Metric name
type: string
example: aws.ec2.cpu.utilization
description: Unique name of the metric
type:
title: Metric type
type: string
enum:
- event
- metric
example: metric
description: Metric type
valueLabel:
title: Metric value label
type: string
maxLength: 100
description: Metric value label
valueFormat:
title: Metric value format
type: string
enum:
- id
- Number
- aws_state
- Kilobytes
- Percentage
- AlertSeverity
- Seconds
- Bytes
- Boolean
example: Percentage
description: Metric value format
metricSelectors:
title: List of metric selectors
type: array
items:
type: string
example: aws.ec2.cpu.utilization
description: List of metric selectors
description: Metric to display on a navigator
description: List of metrics to retrieve and display for the aggregated view of instances in this
navigator.
systemTypes:
title: Navigator system types
type: array
maxItems: 10
items:
type: string
example:
- redis
de
# --- truncated at 32 KB (336 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/splunk-observability/refs/heads/main/openapi/splunk-observability-navigator-openapi.yml