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 Notifications 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: Notifications
description: Operations related to notifications
paths:
/v1/notifications/configurations:
get:
operationId: list-user-configurations
summary: List available user configurations
description: List available user configurations.
parameters:
- $ref: '#/components/parameters/ConfigurationFilter'
responses:
'200':
$ref: '#/components/responses/UserConfigurationListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Notifications
/v1/notifications/configurations/{eventId}/subscriptions:
get:
operationId: list-event-subscriptions
summary: List event subscriptions
description: List event subscriptions.
parameters:
- $ref: '#/components/parameters/eventId'
responses:
'200':
$ref: '#/components/responses/EventSubscriptionListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Notifications
post:
operationId: create-event-subscription
summary: Create a new subscription for an event
description: Create a new subscription for an event.
parameters:
- $ref: '#/components/parameters/eventId'
requestBody:
$ref: '#/components/requestBodies/EventSubscriptionRequest'
responses:
'201':
$ref: '#/components/responses/EventSubscriptionResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Notifications
/v1/notifications/configurations/{eventId}/subscriptions/{subscriptionId}:
parameters:
- $ref: '#/components/parameters/eventId'
- $ref: '#/components/parameters/subscriptionId'
get:
operationId: get-event-subscription
summary: Get subscription for an event
description: Get subscription for an event.
responses:
'200':
$ref: '#/components/responses/EventSubscriptionResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Notifications
patch:
operationId: update-event-subscription
summary: Update subscription for an event
description: Update subscription for an event.
requestBody:
$ref: '#/components/requestBodies/EventSubscriptionRequest'
responses:
'200':
$ref: '#/components/responses/EventSubscriptionResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Notifications
delete:
operationId: delete-event-subscription
summary: Delete subscription associated with event
description: Delete subscription associated with event.
responses:
'204':
description: No Content
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Notifications
/v1/notifications/inbox:
get:
operationId: list-notifications
summary: List available notifications
description: List available notifications.
parameters:
- $ref: '#/components/parameters/PageBefore'
- $ref: '#/components/parameters/PageAfter'
- $ref: '#/components/parameters/NotificationFilter'
responses:
'200':
$ref: '#/components/responses/NotificationListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Notifications
/v1/notifications/inbox/{notificationId}:
get:
operationId: get-notification-details
summary: Get notification details
description: Get notification details.
parameters:
- $ref: '#/components/parameters/notificationId'
responses:
'200':
$ref: '#/components/responses/NotificationResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Notifications
patch:
operationId: update-notification
summary: Update notification
description: Update notification.
parameters:
- $ref: '#/components/parameters/notificationId'
requestBody:
$ref: '#/components/requestBodies/NotificationUpdateRequest'
responses:
'200':
$ref: '#/components/responses/NotificationResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Notifications
delete:
operationId: delete-notification
summary: Delete notification
description: Delete notification.
parameters:
- $ref: '#/components/parameters/notificationId'
responses:
'204':
description: No Content
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Notifications
/v1/notifications/inbox/bulk:
post:
operationId: bulk-notifications
summary: Mark a list of notifications to a status
description: Mark a list of notifications to a status.
requestBody:
$ref: '#/components/requestBodies/BulkRequest'
responses:
'200':
description: No Content
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
tags:
- Notifications
components:
schemas:
InvalidParameterMinimumLength:
type: object
properties:
field:
type: string
example: name
readOnly: true
rule:
description: invalid parameters rules
type: string
enum:
- min_length
- min_digits
- min_lowercase
- min_uppercase
- min_symbols
- min_items
- min
nullable: false
readOnly: true
x-speakeasy-unknown-values: allow
minimum:
type: integer
example: 8
source:
type: string
example: body
reason:
type: string
example: must have at least 8 characters
readOnly: true
additionalProperties: false
required:
- field
- reason
- rule
- minimum
UserConfiguration:
description: Properties of an event.
type: object
properties:
event_id:
type: string
event_title:
type: string
event_description:
type: string
event_namespace:
$ref: '#/components/schemas/NotificationNamespace'
event_subscription_count:
type: integer
default: 0
default_subscription:
type: array
items:
$ref: '#/components/schemas/DefaultSubscription'
required:
- event_id
- event_title
- event_description
- event_namespace
- event_subscription_count
- default_subscription
EntityTypes:
type: string
enum:
- billing-invoice
- access-token
- webhook
- dev-portal
- dataplane-group
- dataplane
- kai-enablement
- enterprise-trial
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
InvalidParameterChoiceItem:
type: object
properties:
field:
type: string
example: name
readOnly: true
rule:
description: invalid parameters rules
type: string
enum:
- enum
nullable: false
readOnly: true
reason:
type: string
example: is a required field
readOnly: true
choices:
type: array
items: {}
minItems: 1
nullable: false
readOnly: true
uniqueItems: true
source:
type: string
example: body
additionalProperties: false
required:
- field
- reason
- rule
- choices
InvalidParameterMaximumLength:
type: object
properties:
field:
type: string
example: name
readOnly: true
rule:
description: invalid parameters rules
type: string
enum:
- max_length
- max_items
- max
nullable: false
readOnly: true
x-speakeasy-unknown-values: allow
maximum:
type: integer
example: 8
source:
type: string
example: body
reason:
type: string
example: must not have more than 8 characters
readOnly: true
additionalProperties: false
required:
- field
- reason
- rule
- maximum
ConfigurationFilterParameters:
type: object
properties:
event_title:
$ref: '#/components/schemas/LegacyStringFieldFilter'
event_description:
$ref: '#/components/schemas/LegacyStringFieldFilter'
event_namespace:
$ref: '#/components/schemas/LegacyStringFieldFilter'
region:
$ref: '#/components/schemas/LegacyStringFieldFilter'
additionalProperties: false
title: ConfigurationFilterParameters
NotificationNamespace:
type: string
enum:
- plan-and-usage
- organization
- dev-portal
- cloud-gateways
- gateway-manager
x-speakeasy-unknown-values: allow
Notification:
description: Properties of a notification.
type: object
properties:
id:
$ref: '#/components/schemas/UUID'
title:
type: string
description:
type: string
status:
$ref: '#/components/schemas/NotificationStatus'
region:
$ref: '#/components/schemas/NotificationRegion'
namespace:
$ref: '#/components/schemas/NotificationNamespace'
entity_id:
description: ID of the entity. Use '*' to represent all entities of this type.
type: string
details:
description: Metadata associated with the notification to build actionable links.
type: object
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
additionalProperties: false
required:
- id
- title
- description
- status
- region
- namespace
- entity_id
- details
- created_at
- updated_at
UUID:
description: Contains a unique identifier used for this resource.
type: string
format: uuid
example: 5f9fd312-a987-4628-b4c5-bb4f4fddd5f7
readOnly: true
LegacyStringFieldFilter:
description: 'Filter using **one** of the following operators: `eq`, `contains`'
type: object
properties:
eq:
description: The field exactly matches the provided value.
type: string
contains:
description: The field contains the provided value.
type: string
additionalProperties: false
DefaultSubscription:
type: object
properties:
channel:
$ref: '#/components/schemas/NotificationChannelType'
enabled:
type: boolean
required:
- channel
- enabled
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
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
CursorMetaPage:
type: object
properties:
first:
description: URI to the first page
type: string
format: path
last:
description: URI to the last page
type: string
format: path
next:
description: URI to the next page
type: string
format: path
nullable: true
previous:
description: URI to the previous page
type: string
format: path
nullable: true
size:
description: Requested page size
type: number
example: 10
required:
- size
- next
- previous
BulkPayload:
description: Request body schema for bulk status update.
type: object
properties:
ids:
type: array
items:
type: string
maxItems: 100
minItems: 1
uniqueItems: true
status:
$ref: '#/components/schemas/NotificationStatus'
required:
- ids
- status
ListCursorMeta:
anyOf:
- $ref: '#/components/schemas/CursorMeta'
- allOf:
- $ref: '#/components/schemas/CursorMetaPage'
deprecated: true
CursorMeta:
description: Pagination metadata.
type: object
properties:
page:
$ref: '#/components/schemas/CursorMetaPage'
required:
- page
EventSubscriptionResponse:
description: Properties associated with an event subscription.
type: object
properties:
id:
$ref: '#/components/schemas/UUID'
entity_type:
$ref: '#/components/schemas/EntityTypes'
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
regions:
type: array
items:
$ref: '#/components/schemas/NotificationRegion'
entities:
type: array
items:
type: string
description: ID of the entity. Use '*' to represent all entities of this type.
channels:
type: array
items:
$ref: '#/components/schemas/NotificationChannel'
enabled:
description: Enable/Disable complete subscription within an event.
type: boolean
name:
description: User provided name of the subscription.
type: string
required:
- id
- entity_type
- created_at
- updated_at
- regions
- entities
- channels
- enabled
- name
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
NotificationStatus:
description: Status of the notification.
type: string
enum:
- READ
- UNREAD
- ARCHIVED
x-speakeasy-unknown-values: allow
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
InvalidParameterDependentItem:
type: object
properties:
field:
type: string
example: name
readOnly: true
rule:
description: invalid parameters rules
type: string
enum:
- dependent_fields
nullable: true
readOnly: true
reason:
type: string
example: is a required field
readOnly: true
dependents:
type: array
items: {}
nullable: true
readOnly: true
uniqueItems: true
source:
type: string
example: body
additionalProperties: false
required:
- field
- rule
- reason
- dependents
InvalidRules:
description: invalid parameters rules
type: string
enum:
- required
- is_array
- is_base64
- is_boolean
- is_date_time
- is_integer
- is_null
- is_number
- is_object
- is_string
- is_uuid
- is_fqdn
- is_arn
- unknown_property
- missing_reference
- is_label
- matches_regex
- invalid
- is_supported_network_availability_zone_list
- is_supported_network_cidr_block
- is_supported_provider_region
- type
nullable: true
readOnly: true
x-speakeasy-unknown-values: allow
NotificationFilterParameters:
type: object
properties:
title:
$ref: '#/components/schemas/LegacyStringFieldFilter'
description:
$ref: '#/components/schemas/LegacyStringFieldFilter'
namespace:
$ref: '#/components/schemas/LegacyStringFieldFilter'
region:
$ref: '#/components/schemas/LegacyStringFieldFilter'
status:
$ref: '#/components/schemas/LegacyStringFieldFilter'
additionalProperties: false
title: NotificationFilterParameters
InvalidParameters:
description: invalid parameters
type: array
items:
oneOf:
- $ref: '#/components/schemas/InvalidParameterStandard'
- $ref: '#/components/schemas/InvalidParameterMinimumLength'
- $ref: '#/components/schemas/InvalidParameterMaximumLength'
- $ref: '#/components/schemas/InvalidParameterChoiceItem'
- $ref: '#/components/schemas/InvalidParameterDependentItem'
minItems: 1
nullable: false
uniqueItems: true
NotificationUpdatePayload:
description: Status of the notification.
type: object
properties:
status:
$ref: '#/components/schemas/NotificationStatus'
required:
- status
BadRequestError:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
required:
- invalid_parameters
properties:
invalid_parameters:
$ref: '#/components/schemas/InvalidParameters'
InvalidParameterStandard:
type: object
properties:
field:
type: string
example: name
readOnly: true
rule:
$ref: '#/components/schemas/InvalidRules'
source:
type: string
example: body
reason:
type: string
example: is a required field
readOnly: true
additionalProperties: false
required:
- field
- reason
NotificationRegion:
description: Region associated to a notification.
type: string
enum:
- US
- EU
- AU
- ME
- IN
- '*'
x-speakeasy-unknown-values: allow
NotificationChannelType:
type: string
enum:
- EMAIL
- IN_APP
x-speakeasy-unknown-values: allow
NotificationChannel:
description: Channel subscription details for an event.
type: object
properties:
type:
$ref: '#/components/schemas/NotificationChannelType'
enabled:
type: boolean
required:
- type
- enabled
EventSubscription:
description: Properties associated with an event subscription.
type: object
properties:
regions:
type: array
items:
$ref: '#/components/schemas/NotificationRegion'
entities:
type: array
items:
type: string
description: ID of the entity. Use '*' to represent all entities of this type.
channels:
type: array
items:
$ref: '#/components/schemas/NotificationChannel'
enabled:
description: Enable/Disable complete subscription within an event.
type: boolean
name:
description: User provided name of the subscription.
type: string
required:
- regions
- entities
- channels
- enabled
- name
NotFoundError:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
properties:
status:
example: 404
title:
example: Not Found
type:
example: https://httpstatuses.com/404
instance:
example: kong:trace:1234567890
detail:
example: Not found
responses:
EventSubscriptionResponse:
description: Response containing specific subscription details associated with an event.
content:
application/json:
schema:
$ref: '#/components/schemas/EventSubscriptionResponse'
NotFound:
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundError'
BadRequest:
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestError'
Forbidden:
description: Forbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ForbiddenError'
UserConfigurationListResponse:
description: A paginated list response for all notification events and user subscriptions.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/UserConfiguration'
additionalProperties: false
required:
- data
NotificationResponse:
description: View a single notification.
content:
application/json:
schema:
$ref: '#/components/schemas/Notification'
Unauthorized:
description: Unauthorized
content:
application/problem+json:
schema:
description: The error response object.
type: object
properties:
status:
description: The HTTP status code.
type: integer
example: 403
title:
description: The Error Response.
type: string
example: Unauthorized
instance:
description: The Konnect traceback code.
type: string
example: konnect:trace:952172606039454040
detail:
description: Details about the error response.
type: string
example: You do not have permission to perform this action
$ref: '#/components/schemas/UnauthorizedError'
title: Unauthorized Response
EventSubscriptionListResponse:
description: A paginated list response for all subscriptions associated with an event.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/EventSubscriptionResponse'
meta:
$ref: '#/components/schemas/ListCursorMeta'
additionalProperties: false
required:
- data
- meta
NotificationListResponse:
description: A paginated list response for a collection of notifications
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Notification'
meta:
$ref: '#/components/schemas/ListCursorMeta'
additionalProperties: false
required:
- data
- meta
parameters:
subscriptionId:
name: subscriptionId
in: path
required: true
description: Subscription ID of the user configuration.
schema:
type: string
PageAfter:
name: page[after]
description: Request the next page of data, starting with the item after this parameter.
required: false
in: query
allowEmptyValue: true
schema:
type: string
example: ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ
eventId:
name: eventId
in: path
required: true
description: Formatted string ID of the notification event.
schema:
type: string
example: invoice-ready
notificationId:
name: notificationId
in: path
required: true
description: ID of the notification.
schema:
type: string
PageBefore:
name: page[before]
description: Request the next page of data, starting with the item before this parameter.
required: false
in: query
allowEmptyValue: true
schema:
type: string
example: ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ
NotificationFilter:
name: filter
description: Filters a collection of notifications.
required: false
in: query
schema:
$ref: '#/components/schemas/NotificationFilterParameters'
style: deepObject
ConfigurationFilter:
name: filter
description: Filters a collection of configurations.
required: false
in: query
schema:
$ref: '#/components/schemas/ConfigurationFilterParameters'
style: deepObject
requestBodies:
BulkRequest:
description: Request body schema for bulk status update.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkPayload'
NotificationUpdateRequest:
description: Request body schema for updating notification status.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationUpdatePayload'
EventSubscriptionRequest:
description: Request body schema for creating/updating event subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/EventSubscription'
securitySchemes:
adminToken:
in: header
name: Kong-Admin-Token
type: apiKey
externalDocs:
description: Documentation for Kong Gateway and its APIs
url: https://developer.konghq.com