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 API 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: API
paths:
/v3/apis:
post:
x-speakeasy-entity-operation:
terraform-resource: Api#create
terraform-datasource: null
operationId: create-api
summary: Create API
description: Creates an API.
requestBody:
$ref: '#/components/requestBodies/CreateApiRequest'
responses:
'201':
$ref: '#/components/responses/ApiResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
$ref: '#/components/responses/ApiUnauthorized'
'403':
$ref: '#/components/responses/ApiForbidden'
'404':
$ref: '#/components/responses/ApiNotFound'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
tags:
- API
get:
operationId: list-apis
summary: List APIs
description: Returns a collection of all APIs.
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageNumber'
- $ref: '#/components/parameters/ApiFilters'
- $ref: '#/components/parameters/ApiSort'
responses:
'200':
$ref: '#/components/responses/ListApiResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
$ref: '#/components/responses/ApiUnauthorized'
'403':
$ref: '#/components/responses/ApiForbidden'
'404':
$ref: '#/components/responses/ApiNotFound'
tags:
- API
/v3/apis/{apiId}:
parameters:
- name: apiId
in: path
description: The UUID API identifier
required: true
schema:
type: string
format: uuid
example: 9f5061ce-78f6-4452-9108-ad7c02821fd5
x-speakeasy-match: id
get:
x-speakeasy-entity-operation:
terraform-resource: Api#read
terraform-datasource: null
operationId: fetch-api
summary: Get an API
description: Get an API.
responses:
'200':
$ref: '#/components/responses/ApiResponse'
'401':
$ref: '#/components/responses/ApiUnauthorized'
'403':
$ref: '#/components/responses/ApiForbidden'
'404':
$ref: '#/components/responses/ApiNotFound'
tags:
- API
patch:
x-speakeasy-entity-operation:
terraform-resource: Api#update
terraform-datasource: null
operationId: update-api
summary: Update API
description: Updates an API.
parameters:
- name: force
in: query
description: 'If true, allows operations to be removed from the current version when using access control enforcement.
If false, operations removal will be rejected with a 409 error.
Omitting the value means true.
'
schema:
type: string
default: 'false'
enum:
- 'true'
- 'false'
requestBody:
$ref: '#/components/requestBodies/UpdateApiRequest'
responses:
'200':
$ref: '#/components/responses/ApiResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
$ref: '#/components/responses/ApiUnauthorized'
'403':
$ref: '#/components/responses/ApiForbidden'
'404':
$ref: '#/components/responses/ApiNotFound'
'409':
$ref: '#/components/responses/ApiVersionPatchConflict'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
tags:
- API
delete:
x-speakeasy-entity-operation:
terraform-resource: Api#delete
terraform-datasource: null
operationId: delete-api
summary: Delete API
description: Deletes an API.
responses:
'204':
description: API was deleted successfully.
'401':
$ref: '#/components/responses/ApiUnauthorized'
'403':
$ref: '#/components/responses/ApiForbidden'
'404':
$ref: '#/components/responses/ApiNotFound'
tags:
- API
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
ApiVersionSummary:
type: object
properties:
id:
description: The API version identifier.
type: string
format: uuid
example: 7710d5c4-d902-410b-992f-18b814155b53
readOnly: true
version:
description: The version of this api spec.
type: string
spec:
type: object
additionalProperties: false
properties:
type:
$ref: '#/components/schemas/ApiSpecType'
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
additionalProperties: false
nullable: true
readOnly: true
title: API Version Summary
x-speakeasy-terraform-ignore: true
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
ConflictError:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
properties:
status:
example: 409
title:
example: Conflict
type:
example: https://httpstatuses.com/409
instance:
example: kong:trace:1234567890
detail:
example: Conflict
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
ApiAttributes:
description: A set of attributes that describe the API
type: object
example:
env:
- production
domains:
- web
- mobile
default: {}
additionalProperties:
nullable: true
description: Set of attributes with unique keys. Each key can include lowercase letters, numbers, hyphens, and underscores.
type: array
minItems: 1
maxItems: 20
items:
type: string
minLength: 1
maxLength: 512
pattern: ^[^,<>]*$
nullable: false
title: API Attributes
x-speakeasy-type-override: any
ApiResponseSchema:
type: object
properties:
id:
description: The API identifier.
type: string
format: uuid
example: 9f5061ce-78f6-4452-9108-ad7c02821fd5
readOnly: true
name:
description: 'The name of your API. The `name + version` combination must be unique for each API you publish.
'
type: string
example: MyAPI
maxLength: 255
minLength: 1
description:
description: A description of your API. Will be visible on your live Portal.
type: string
nullable: true
version:
description: An optional version for your API. Leave this empty if your API is unversioned.
type: string
maxLength: 255
minLength: 1
nullable: true
x-speakeasy-param-computed: true
current_version_summary:
$ref: '#/components/schemas/ApiVersionSummary'
slug:
description: 'The `slug` is used in generated URLs to provide human readable paths.
Defaults to `slugify(name + version)`
'
type: string
example: my-api-v1
nullable: true
pattern: ^[\w-]+$
x-speakeasy-param-computed: true
api_spec_ids:
description: The list of API specification ids for the API.
type: array
items:
type: string
format: uuid
description: The id of the API specification.
example: 123e4567-e89b-12d3-a456-426614174000
deprecated: true
readOnly: true
portals:
description: The list of portals which this API is published to.
type: array
items:
type: object
additionalProperties: false
required:
- id
- name
- display_name
properties:
id:
description: The portal identifier.
type: string
format: uuid
example: 25a2624c-49fc-4764-99e1-224ed819f200
name:
description: The name of the portal, used to distinguish it from other portals.
type: string
example: My Portal
display_name:
description: The display name of the portal. This value will be the portal's `name` in Portal API.
type: string
example: My Portal
nullable: false
readOnly: true
uniqueItems: true
labels:
$ref: '#/components/schemas/Labels'
implementation_mode:
description: the implementations that are associated with this api either gateway_entity_binding or access_control_enforcement
type: string
nullable: true
readOnly: true
attributes:
$ref: '#/components/schemas/ApiAttributes'
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
additionalProperties: false
required:
- id
- name
- version
- labels
- created_at
- updated_at
- slug
- portals
- api_spec_ids
- current_version_summary
title: API
ApiFilterParameters:
type: object
properties:
id:
$ref: '#/components/schemas/UuidFieldFilter'
name:
$ref: '#/components/schemas/StringFieldFilter'
version:
$ref: '#/components/schemas/StringFieldFilter'
labels:
$ref: '#/components/schemas/LabelsFieldFilter'
attributes:
$ref: '#/components/schemas/AttributesFieldFilter'
implementation_mode:
$ref: '#/components/schemas/StringFieldFilter'
created_at:
$ref: '#/components/schemas/DateTimeFieldFilter'
updated_at:
$ref: '#/components/schemas/DateTimeFieldFilter'
title: API Filter Parameters
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
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
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
AttributesFieldFilter:
allOf:
- title: AttributesFieldFilter
description: "Filters on the resource's `attributes` field. Filters must use dot-notation to identify\nthe attribute key that will be used to filter the results. For example:\n\n\n - `filter[attributes.owner]`\n - `filter[attributes.owner][neq]=kong`\n - `filter[attributes.env]=dev`\n - `filter[attributes.env][ocontains]=dev,test`\n"
- $ref: '#/components/schemas/StringFieldFilter'
LabelsUpdate:
description: "Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. \n\nLabels are intended to store **INTERNAL** metadata.\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
nullable: true
maxProperties: 50
nullable: true
writeOnly: true
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
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
ApiSpecType:
description: 'The type of specification being stored. This allows us to render the specification correctly.
'
type: string
example: oas3
enum:
- oas2
- oas3
- asyncapi
title: API Spec Type
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
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
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
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
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
DateTimeFieldFilter:
description: Filters on the given datetime (RFC-3339) field value.
oneOf:
- type: object
title: DateTimeFieldEqualsFilter
additionalProperties: false
properties:
eq:
description: Value strictly equals given RFC-3339 formatted timestamp in UTC
type: string
format: date-time
example: '2022-03-30T07:20:50Z'
required:
- eq
- type: object
title: DateTimeFieldLTFilter
additionalProperties: false
properties:
lt:
description: Value is less than the given RFC-3339 formatted timestamp in UTC
type: string
format: date-time
example: '2022-03-30T07:20:50Z'
required:
- lt
- type: object
title: DateTimeFieldLTEFilter
additionalProperties: false
properties:
lte:
description: Value is less than or equal to the given RFC-3339 formatted timestamp in UTC
type: string
format: date-time
example: '2022-03-30T07:20:50Z'
required:
- lte
- type: object
title: DateTimeFieldGTFilter
additionalProperties: false
properties:
gt:
description: Value is greater than the given RFC-3339 formatted timestamp in UTC
type: string
format: date-time
example: '2022-03-30T07:20:50Z'
required:
- gt
- type: object
title: DateTimeFieldGTEFilter
additionalProperties: false
properties:
gte:
description: Value is greater than or equal to the given RFC-3339 formatted timestamp in UTC
type: string
format: date-time
example: '2022-03-30T07:20:50Z'
required:
- gte
title: DateTimeFieldFilter
UnsupportedMediaTypeError:
allOf:
- $ref: '#/components/schemas/BaseError'
- type: object
properties:
status:
example: 415
title:
example: UnsupportedMediaType
type:
example: https://httpstatuses.com/415
instance:
example: kong:trace:1234567890
detail:
example: UnsupportedMediaType
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
PageMeta:
description: Contains pagination query parameters and the total number of objects returned.
type: object
properties:
number:
type: number
example: 1
x-speakeasy-terraform-ignore: true
size:
type: number
example: 10
x-speakeasy-terraform-ignore: true
total:
type: number
example: 100
x-speakeasy-terraform-ignore: true
required:
- number
- size
- total
LabelsFieldFilter:
allOf:
- title: LabelsFieldFilter
description: "Filters on the resource's `labels` field. Filters must use dot-notation to identify\nthe label key that will be used to filter the results. For example:\n\n\n - `filter[labels.owner]`\n - `filter[labels.owner][neq]=kong`\n - `filter[labels.env]=dev`\n - `filter[labels.env][ocontains]=dev,test`\n"
- $ref: '#/components/schemas/StringFieldFilter'
responses:
ListApiResponse:
description: List of APIs
content:
application/json:
schema:
type: object
properties:
meta:
$ref: '#/components/schemas/PaginatedMeta'
data:
type: array
items:
$ref: '#/components/schemas/ApiResponseSchema'
additionalProperties: false
required:
- data
- meta
title: ListApiResponse
ApiUnauthorized:
description: ApiUnauthorized
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
ApiNotFound:
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundError'
ApiForbidden:
description: ApiForbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ForbiddenError'
ApiResponse:
description: API
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponseSchema'
ApiVersionPatchConflict:
description: Conflict - May occur when constraints are violated
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ConflictError'
UnsupportedMediaType:
description: Unsupported Media Type
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeError'
requestBodies:
UpdateApiRequest:
required: true
content:
application/json:
schema:
type: object
properties:
id:
description: The API identifier.
type: string
format: uuid
example: 9f5061ce-78f6-4452-9108-ad7c02821fd5
readOnly: true
name:
description: 'The name of your API. The `name + version` combination must be unique for each API you publish.
'
type: string
example: MyAPI
maxLength: 255
minLength: 1
description:
description: A description of your API. Will be visible on your live Portal.
type: string
nullable: true
version:
description: An optional version for your API. Leave this empty if your API is unversioned.
type: string
maxLength: 255
minLength: 1
nullable: true
x-speakeasy-param-computed: true
current_version_summary:
$ref: '#/components/schemas/ApiVersionSummary'
slug:
description: 'The `slug` is used in generated URLs to provide human readable paths.
Defaults to `slugify(name + version)`
'
type: string
example: my-api-v1
nullable: true
pattern: ^[\w-]+$
x-speakeasy-param-computed: true
api_spec_ids:
description: The list of API specification ids for the API.
type: array
items:
type: string
format: uuid
description: The id of the API specification.
example: 123e4567-e89b-12d3-a456-426614174000
deprecated: true
readOnly: true
portals:
description: The list of portals which this API is published to.
type: array
items:
type: object
additionalProperties: false
required:
- id
- name
- display_name
properties:
id:
description: The portal identifier.
type: string
format: uuid
example: 25a2624c-49fc-4764-99e1-224ed819f200
name:
description: The name of the portal, used to distinguish it from other portals.
type: string
example: My Portal
display_name:
description: The display name of the portal. This value will be the portal's `name` in Portal API.
type: string
example: My Portal
nullable: false
readOnly: true
uniqueItems: true
labels:
$ref: '#/components/schemas/LabelsUpdate'
implementation_mode:
description: the implementations that are associated with this api either gateway_entity_binding or access_control_enforcement
type: string
nullable: true
readOnly: true
attributes:
$ref: '#/components/schemas/ApiAttributes'
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
additionalProperties: false
title: API
CreateApiRequest:
required: true
content:
application/json:
schema:
type: object
properties:
id:
description: The API identifier.
type: string
format: uuid
example: 9f5061ce-78f6-4452-9108-ad7c02821fd5
readOnly: true
name:
de
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kong/refs/heads/main/openapi/kong-api-api-openapi.yml