openapi: 3.1.0
info:
contact:
email: support@konghq.com
name: Kong Inc
url: https://konghq.com
description: 'OpenAPI 3.0 spec for Kong Gateway''s Admin API.
You can learn more about Kong Gateway at [developer.konghq.com](https://developer.konghq.com).
Give Kong a star at the [Kong/kong](https://github.com/kong/kong) repository.'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
title: Kong Enterprise Admin ACLs Dashboards API
version: 3.14.0
servers:
- description: Default Admin API URL
url: '{protocol}://{hostname}:{port}{path}'
variables:
hostname:
default: localhost
description: Hostname for Kong's Admin API
path:
default: /
description: Base path for Kong's Admin API
port:
default: '8001'
description: Port for Kong's Admin API
protocol:
default: http
description: Protocol for requests to Kong's Admin API
enum:
- http
- https
security:
- adminToken: []
tags:
- name: Dashboards
paths:
/v2/dashboards:
get:
operationId: dashboards-list
summary: List dashboards
description: Get a paginated list of dashboards that your account has access to.
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageNumber'
- $ref: '#/components/parameters/DashboardListFilters'
- $ref: '#/components/parameters/DashboardSort'
responses:
'200':
description: List of dashboards
content:
application/json:
schema:
type: object
properties:
meta:
$ref: '#/components/schemas/PaginatedMeta'
data:
type: array
items:
$ref: '#/components/schemas/DashboardResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Dashboards
post:
x-speakeasy-entity-operation:
terraform-resource: Dashboard#create
terraform-datasource: null
operationId: dashboards-create
summary: Create a new dashboard
description: Creates a new dashboard from the provided definition.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardUpdateRequest'
responses:
'201':
description: The created dashboard, including generated fields.
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardResponse'
'400':
description: Bad request; returned when the request payload was not valid.
content:
application/problem+json: {}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Dashboards
/v2/dashboards/{dashboardId}:
parameters:
- name: dashboardId
in: path
description: The dashboard's ID.
required: true
schema:
type: string
format: uuid
example: d32d905a-ed33-46a3-a093-d8f536af9a8a
x-speakeasy-match: id
get:
x-speakeasy-entity-operation:
terraform-resource: Dashboard#read
terraform-datasource: null
operationId: dashboards-get
summary: Get a single dashboard
description: Get a dashboard that your account has access to.
responses:
'200':
description: The dashboard with the given ID.
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Dashboards
put:
x-speakeasy-entity-operation:
terraform-resource: Dashboard#update
terraform-datasource: null
operationId: dashboards-update
summary: Update an existing dashboard
description: Update an existing dashboard, replacing its definition with the provided one.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardUpdateRequest'
responses:
'200':
description: The created dashboard, including generated fields.
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardResponse'
'400':
description: Bad request; returned when the request payload was not valid.
content:
application/problem+json: {}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Dashboards
delete:
x-speakeasy-entity-operation:
terraform-resource: Dashboard#delete
terraform-datasource: null
operationId: dashboards-delete
summary: Delete an existing dashboard
description: Delete an existing dashboard.
responses:
'204':
description: No Content
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Dashboards
components:
schemas:
Granularity:
description: "Force time grouping into buckets of the specified duration. Only has an effect if \"time\" is in the \"dimensions\" list.\n\nThe granularity of the result may be coarser than requested. The finest allowed granularity depends on the query's time range: data farther in the past may have coarser granularity. The exact result granularity will be reported in the response `meta.granularity_ms` field.\n\nIf granularity is not specified and \"time\" is in the dimensions list, a default will be chosen based on the time range requested.\n\nDifferent relative times support different granularities:\n\n\n - 15m => tenSecondly, thirtySecondly, minutely\n - 1h => tenSecondly, thirtySecondly, minutely, fiveMinutely, tenMinutely\n - 6h => thirtySecondly, minutely, fiveMinutely, tenMinutely, thirtyMinutely, hourly\n - 12h => minutely, fiveMinutely, tenMinutely, thirtyMinutely, hourly\n - 24h => fiveMinutely, tenMinutely, thirtyMinutely, hourly\n - 7d => thirtyMinutely, hourly, twoHourly, twelveHourly, daily\n - 30d => hourly, twoHourly, twelveHourly, daily, weekly\n\nFor special time ranges:\n\n\n - current_week, previous_week => thirtyMinutely, hourly, twoHourly, twelveHourly, daily\n - current_month, previous_month => hourly, twoHourly, twelveHourly, daily, weekly\n\nFor absolute time ranges, daily will be used.\n"
type: string
enum:
- tenSecondly
- thirtySecondly
- minutely
- fiveMinutely
- tenMinutely
- thirtyMinutely
- hourly
- twoHourly
- twelveHourly
- daily
- weekly
x-speakeasy-unknown-values: allow
UpdatedAt:
description: An ISO-8601 timestamp representation of entity update date.
type: string
format: date-time
example: '2022-11-04T20:10:06.927Z'
readOnly: true
x-speakeasy-param-suppress-computed-diff: true
LLMFilters:
description: A list of filters to apply to the query.
type: array
items:
type: object
properties:
field:
type: string
enum:
- ai_plugin
- ai_provider
- ai_request_model
- ai_response_model
- application
- consumer
- control_plane
- control_plane_group
- gateway_service
- llm_cache_status
- llm_embeddings_model
- llm_embeddings_provider
- realm
- route
- status_code
- status_code_grouped
x-speakeasy-unknown-values: allow
operator:
type: string
enum:
- in
- not_in
- empty
- not_empty
x-speakeasy-unknown-values: allow
value:
x-speakeasy-type-override: any
required:
- field
- operator
LLMMetrics:
description: List of aggregated metrics to collect across the requested time span.
type: array
items:
type: string
enum:
- total_tokens
- prompt_tokens
- completion_tokens
- ai_request_count
- cost
- llm_cache_embeddings_latency_average
- llm_cache_fetch_latency_average
- llm_latency_average
- llm_embeddings_tokens
- llm_embeddings_cost
x-speakeasy-unknown-values: allow
default:
- ai_request_count
AgenticQuery:
description: A query targeting the agentic usage analytics datasource.
type: object
properties:
datasource:
type: string
enum:
- agentic_usage
metrics:
$ref: '#/components/schemas/AgenticMetrics'
dimensions:
description: List of attributes or entity types to group by.
type: array
items:
type: string
enum:
- a2a_context_id
- a2a_error
- a2a_method
- a2a_task_id
- api
- api_package
- api_product
- api_product_version
- application
- consumer
- control_plane
- control_plane_group
- country_code
- data_plane_node
- data_plane_node_version
- gateway_service
- mcp_error
- mcp_method
- mcp_session_id
- mcp_tool_name
- portal
- realm
- response_source
- route
- status_code
- status_code_grouped
- time
- upstream_status_code
- upstream_status_code_grouped
x-speakeasy-unknown-values: allow
maxItems: 2
filters:
$ref: '#/components/schemas/AgenticFilters'
granularity:
$ref: '#/components/schemas/Granularity'
time_range:
$ref: '#/components/schemas/TimeRange'
example:
datasource: agentic_usage
time_range:
type: relative
time_range: 24h
tz: EST
dimensions:
- time
- mcp_tool_name
filters:
- operator: in
field: control_plane
value:
- d5ac5d88-efed-4e10-9dfe-0b0a6646c219
granularity: hourly
metrics:
- request_count
additionalProperties: false
required:
- datasource
AdvancedFilters:
description: A list of filters to apply to the query.
type: array
items:
type: object
properties:
field:
type: string
enum:
- api
- api_package
- api_product
- api_product_version
- application
- consumer
- control_plane
- control_plane_group
- country_code
- data_plane_node
- data_plane_node_version
- gateway_service
- portal
- realm
- response_source
- route
- status_code
- status_code_grouped
- upstream_status_code
- upstream_status_code_grouped
x-speakeasy-unknown-values: allow
operator:
type: string
enum:
- in
- not_in
- empty
- not_empty
x-speakeasy-unknown-values: allow
value:
x-speakeasy-type-override: any
required:
- field
- operator
DashboardUpdateRequest:
type: object
properties:
name:
description: 'The dashboard name, which is displayed at the top of the dashboard and in lists.
It does not need to be unique.
'
type: string
maxLength: 255
minLength: 1
definition:
$ref: '#/components/schemas/Dashboard'
labels:
$ref: '#/components/schemas/Labels'
required:
- name
- definition
title: Dashboard Request
UuidFieldFilter:
description: 'Filter using **one** of the following operators: `eq`, `oeq`, `neq`'
type: object
properties:
eq:
description: The field exactly matches the provided value.
type: string
oeq:
description: The field matches any of the provided values.
type: string
neq:
description: The field does not match the provided value.
type: string
additionalProperties: false
AgenticFilters:
description: A list of filters to apply to the query.
type: array
items:
type: object
properties:
field:
type: string
enum:
- a2a_context_id
- a2a_error
- a2a_method
- a2a_task_id
- api
- api_package
- api_product
- api_product_version
- application
- consumer
- control_plane
- control_plane_group
- country_code
- data_plane_node
- data_plane_node_version
- gateway_service
- mcp_error
- mcp_method
- mcp_session_id
- mcp_tool_name
- portal
- realm
- response_source
- route
- status_code
- status_code_grouped
- upstream_status_code
- upstream_status_code_grouped
x-speakeasy-unknown-values: allow
operator:
type: string
enum:
- in
- not_in
- empty
- not_empty
x-speakeasy-unknown-values: allow
value:
x-speakeasy-type-override: any
required:
- field
- operator
UUID:
description: Contains a unique identifier used for this resource.
type: string
format: uuid
example: 5f9fd312-a987-4628-b4c5-bb4f4fddd5f7
readOnly: true
LLMQuery:
description: A query targeting the LLM usage analytics datasource.
type: object
properties:
datasource:
type: string
enum:
- llm_usage
metrics:
$ref: '#/components/schemas/LLMMetrics'
dimensions:
description: List of attributes or entity types to group by.
type: array
items:
type: string
enum:
- control_plane
- control_plane_group
- gateway_service
- consumer
- application
- route
- ai_provider
- ai_response_model
- ai_request_model
- llm_cache_status
- llm_embeddings_provider
- llm_embeddings_model
- time
- realm
- status_code
- status_code_grouped
- ai_plugin
x-speakeasy-unknown-values: allow
maxItems: 2
filters:
$ref: '#/components/schemas/LLMFilters'
granularity:
$ref: '#/components/schemas/Granularity'
time_range:
$ref: '#/components/schemas/TimeRange'
example:
datasource: llm_usage
time_range:
type: relative
time_range: 24h
tz: EST
dimensions:
- time
- ai_plugin
filters:
- operator: in
field: control_plane
value:
- d5ac5d88-efed-4e10-9dfe-0b0a6646c219
granularity: hourly
metrics:
- total_tokens
additionalProperties: false
required:
- datasource
Labels:
description: "Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. \n\nKeys must be of length 1-63 characters, and cannot start with \"kong\", \"konnect\", \"mesh\", \"kic\", or \"_\".\n"
type: object
example:
env: test
additionalProperties:
type: string
pattern: ^[a-z0-9A-Z]{1}([a-z0-9A-Z-._]*[a-z0-9A-Z]+)?$
minLength: 1
maxLength: 63
maxProperties: 50
title: Labels
ForbiddenError:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
properties:
status:
example: 403
title:
example: Forbidden
type:
example: https://httpstatuses.com/403
instance:
example: kong:trace:1234567890
detail:
example: Forbidden
UnauthorizedError:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
properties:
status:
example: 401
title:
example: Unauthorized
type:
example: https://httpstatuses.com/401
instance:
example: kong:trace:1234567890
detail:
example: Invalid credentials
MetricsRelativeTimeRangeDtoV2:
description: A duration representing a relative-to-now span of time. Generally the start time is floored to the requested granularity. Eg 7d from now, with 1day granularity initiated at 2024-01-08T17:11:00+05:00 will query for the time range from 2024-01-01T00:00:00+05:00 to 2024-01-08T17:11:00+05:00. The exact start and end timestamps are returned in the result query in the meta.start and meta.end fields. If the granularity for the previous query was 1hour, it would query a time range from 2024-01-01T17:00:00+05:00 to 2024-01-08T17:11:00+05:00.
type: object
properties:
tz:
type: string
default: Etc/UTC
type:
type: string
enum:
- relative
time_range:
type: string
default: 1h
enum:
- 15m
- 1h
- 6h
- 12h
- 24h
- 7d
- 30d
- current_week
- current_month
- previous_week
- previous_month
x-speakeasy-unknown-values: allow
required:
- type
- time_range
title: Relative time range
DonutChart:
description: 'A chart that can display one-dimensional data in a hollow, segmented circle. To use this chart, ensure that
the query includes only one dimension (not `time`).
'
type: object
properties:
chart_title:
description: The title of the chart, which is displayed in the tile's header.
type: string
nullable: false
type:
type: string
enum:
- donut
additionalProperties: false
required:
- type
title: Donut chart
ChoroplethMapChart:
description: 'A chart that displays data on a world map. Each region on the map is colored based on the metric value.
This chart works only with the `api_usage` datasource and requires a single metric and a single dimension of `country_code`.
No additional dimensions are supported.
'
type: object
properties:
chart_title:
description: The title of the chart, which is displayed in the tile's header.
type: string
nullable: false
type:
type: string
enum:
- choropleth_map
additionalProperties: false
required:
- type
title: Choropleth map chart
DashboardFilterParameters:
type: object
properties:
id:
$ref: '#/components/schemas/UuidFieldFilter'
name:
$ref: '#/components/schemas/StringFieldFilter'
labels:
$ref: '#/components/schemas/LabelsFieldFilter'
created_at:
$ref: '#/components/schemas/DateTimeFieldFilter'
updated_at:
$ref: '#/components/schemas/DateTimeFieldFilter'
title: Dashboard Filter Parameters
PaginatedMeta:
description: returns the pagination information
type: object
properties:
page:
$ref: '#/components/schemas/PageMeta'
required:
- page
title: PaginatedMeta
x-speakeasy-terraform-ignore: true
StringFieldFilter:
description: 'Filter using **one** of the following operators: `eq`, `oeq`, `neq`, `contains`, `ocontains`'
type: object
properties:
eq:
description: The field exactly matches the provided value.
type: string
contains:
description: The field contains the provided value.
type: string
ocontains:
description: The field contains any of the provided values.
type: string
oeq:
description: The field matches any of the provided values.
type: string
neq:
description: The field does not match the provided value.
type: string
additionalProperties: false
SingleValueChart:
description: A chart that can render a single number. This chart works with a single metric and no dimensions.
type: object
properties:
chart_title:
description: The title of the chart, which is displayed in the tile's header.
type: string
nullable: false
type:
type: string
enum:
- single_value
decimal_points:
description: The number of figures to render after the decimal. Most metrics only support up to 2 decimals, but some may support more.
type: number
additionalProperties: false
required:
- type
title: Single value chart
Dashboard:
description: 'A JSON object describing a dashboard.
A dashboard is an array of tiles. All tiles are of type ''chart'', which query data and render a chart displaying that data.
Dashboards have 6 columns and as many rows as necessary to display their tiles.
'
type: object
properties:
tiles:
description: The array of tiles. We currently support up to 102 tiles, which is 17 rows of 6x1 tiles.
type: array
items:
$ref: '#/components/schemas/Tile'
maxLength: 102
minLength: 0
preset_filters:
description: 'An optional array of filters that are applied globally to all relevant tiles in the dashboard.
Whether or not a preset filter applies to a tile depends on the filter''s dimension. Some dimensions, like `control_plane`, are common to all datasources; other dimensions may only apply to one datasource.
'
type: array
items:
$ref: '#/components/schemas/AllFilterItems'
example:
- operator: in
field: control_plane
value:
- 00000000-0000-0000-0000-000000000000
- operator: in
field: ai_request_model
value:
- request_model1
nullable: false
additionalProperties: false
required:
- tiles
BarChart:
description: 'A chart that can display non-timeseries data as bars. This type of chart supports up to 2 dimensions (not `time`).
To render a bar chart of timeseries data, use a `timeseries_bar` chart instead.
'
type: object
properties:
chart_title:
description: The title of the chart, which is displayed in the tile's header.
type: string
nullable: false
type:
type: string
enum:
- horizontal_bar
- vertical_bar
x-speakeasy-unknown-values: allow
stacked:
description: 'Whether to stack the bars (implicitly adding them together to form a total), or leave them independent from each other.
'
type: boolean
nullable: false
additionalProperties: false
required:
- type
title: Bar chart
CreatedAt:
description: An ISO-8601 timestamp representation of entity creation date.
type: string
format: date-time
example: '2022-11-04T20:10:06.927Z'
readOnly: true
x-speakeasy-param-suppress-computed-diff: true
BaseError:
description: standard error
type: object
properties:
status:
description: 'The HTTP status code of the error. Useful when passing the response
body to child properties in a frontend UI. Must be returned as an integer.
'
type: integer
readOnly: true
title:
description: 'A short, human-readable summary of the problem. It should not
change between occurences of a problem, except for localization.
Should be provided as "Sentence case" for direct use in the UI.
'
type: string
readOnly: true
type:
description: The error type.
type: string
readOnly: true
instance:
description: 'Used to return the correlation ID back to the user, in the format
kong:trace:<correlation_id>. This helps us find the relevant logs
when a customer reports an issue.
'
type: string
readOnly: true
detail:
description: 'A human readable explanation specific to this occurence of the problem.
This field may contain request/entity data to help the user understand
what went wrong. Enclose variable values in square brackets. Should be
provided as "Sentence case" for direct use in the UI.
'
type: string
readOnly: true
required:
- status
- title
- instance
- detail
title: Error
AllFilterItems:
type: object
properties:
field:
type: string
enum:
- a2a_context_id
- a2a_error
- a2a_method
- a2a_task_id
- ai_plugin
- ai_provider
- ai_request_model
- ai_response_model
- api
- api_package
- api_product
- api_product_version
- application
- consumer
- control_plane
- control_plane_group
- country_code
- data_plane_node
- data_plane_node_version
- gateway_service
- llm_cache_status
- llm_embeddings_model
- llm_embeddings_provider
- mcp_error
- mcp_method
- mcp_session_id
- mcp_tool_name
- portal
- realm
- response_source
- route
- status_code
- status_code_grouped
- upstream_status_code
- upstream_status_code_grouped
x-speakeasy-unknown-values: allow
operator:
type: string
enum:
- in
- not_in
- empty
- not_empty
x-speakeasy-unknown-values: allow
value:
x-speakeasy-type-override: any
required:
- field
- operator
SortQuery:
description: 'The `asc` suffix is optional as the default sort order is ascending.
The `desc` suffix is used to specify a descending order.
Multiple sort attributes may be provided via a comma separated list.
JSONPath notation may be used to specify a sub-attribute (eg: ''foo.bar desc'').
'
type: string
example: created_at desc
title: SortQuery
AdvancedQuery:
description: A query targeting the API usage analytics datasource.
type: object
properties:
datasource:
type: string
enum:
- api_usage
metrics:
$ref: '#/components/schemas/AdvancedMetrics'
dimensions:
description: List of attributes or entity types to group by.
type: array
items:
type: string
enum:
- api
- api_package
- api_product
- api_product_version
- application
- consumer
- control_plane
- control_plane_group
- country_code
- data_plane_node
- data_plane_node_version
- gateway_service
- portal
- response_source
- realm
- route
- status_code
- status_code_grouped
- time
- upstream_status_code
- upstream_status_code_grouped
x-speakeasy-unknown-values: allow
example:
- status_code_grouped
maxItems: 2
filters:
$ref: '#/components/schemas/AdvancedFilters'
granularity:
$ref: '#/components/schemas/Granularity'
time_range:
$ref: '#/components/schemas/TimeRange'
example:
datasource: api_usage
time_range:
type: relative
time_range: 24h
tz: EST
dimensions:
- time
- gateway_service
filters:
- operator: in
field: control_plane
value:
- d5ac5d88-efed-4e10-9dfe-0b0a6646c219
granularity: hourly
metrics:
- request_count
- response_latency_p99
additionalProperties: false
required:
- datasource
TimeseriesChart:
description: "A chart that can render timeseries data -- data from a query that has `time` as a dimension -- as lines or bars.\n\nThis type of chart can support:\n\n- One or more metrics: `{ metrics: [\"response_latency_p99\", \"response_latency_p95\"], dimensions: [\"time\"] }`\n- One metric plus one non-time dimension: `{ metrics: [\"request_count\"], dimensions: [\"time\", \"gateway_service\"] }` \n\nEither way, ensure that `time` is in the list of query dimensions.\n"
type: object
properties:
chart_title:
description: The title of the chart, which is displayed in the tile's header.
type: string
nullable: false
type:
type: string
enum:
- timeseries_line
- timeseries_bar
x-speakeasy-unknown-values: allow
stacked:
description: 'Whether to stack the bars or lines (implicitly adding them together to form a total), or leave them independent from each other.
'
type: boolean
nullable: false
additionalProperties: false
required:
- type
title: Timeseries chart
Tile:
discriminator:
propertyName: type
mapping:
chart: '#/components/schemas/ChartTile'
oneOf:
- $ref: '#/components/schemas/ChartTile'
AdvancedMetrics:
description: List of aggregated metrics to collect across the requested time span. If no metrics are specified, request_count will be computed by default.
type: array
items:
type: string
enum:
- kong_latency_average
- kong_latency_p50
- kong_latency_p95
- kong_latency_p99
- request_count
- request_per_minute
- request_size_average
- request_size_p50
- request_size_p95
- request_size_p99
- request_size_sum
- response_latency_average
- response_latency_p50
- response_latency_p95
- response_latency_p99
- response_size_average
- response_size_p50
- response_size_p95
- response_size_p99
- response_size_sum
- upstream_latency_average
- upstream_latency_p50
- upstream_latency_p95
- upstream_latency_p99
x-speakeasy-unknown-values: allow
default:
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kong/refs/heads/main/openapi/kong-dashboards-api-openapi.yml